khive_db/writer_task.rs
1//! Single-writer task and bounded write queue (ADR-067 Component A).
2//!
3//! `WriterTask` (via `spawn` and the drain loop `run_writer_task`) owns a
4//! dedicated standalone writer `rusqlite::Connection` and is the only code
5//! path that issues `BEGIN IMMEDIATE` for write traffic routed through the
6//! channel it drains. Callers reach it exclusively through a
7//! [`WriterTaskHandle`], sending a typed closure and awaiting a typed
8//! oneshot reply so each store method's natural return type (e.g.
9//! `BatchWriteSummary`) survives the trip through the type-erased channel
10//! unmodified — a flat `Result<u64, StorageError>` reply would conflate
11//! `affected`/`failed` into one count and drop `first_error`.
12//!
13//! See `crates/khive-db/docs/api/writer-task.md` for migration-slice scope
14//! (which write paths currently route through this vs. the legacy
15//! pool-mutex path) and the ADR-067 component breakdown.
16//!
17//! ## ADR-136 D1 gate 5: writer classification
18//!
19//! Every connection that issues writes against a khive-db file falls into
20//! exactly one of the rows below. Request-path store writes, runtime
21//! merge/symmetric-edge transactions,
22//! and `khive_storage::SqlAccess` (`SqlBridge::writer`/`atomic_unit`) are subject
23//! to `PoolConfig::write_queue_enabled` / `write_routing_strict` routing.
24//! Everything else here is an
25//! explicit, intentional exemption — not an implicit gap left over from an
26//! incomplete migration.
27//!
28//! | Writer | Connection | Request-path write | Routing |
29//! | --- | --- | --- | --- |
30//! | Request-path writes (`create`, `update`, batch upserts, …) | `WriterTaskHandle` (queue-first) or a standalone/pool-mutex connection on degrade | Yes | Queue-first (ADR-136 D1 gate 1); strict routing fails closed on degrade |
31//! | Startup / schema migrations (`migrations::run_migrations`, `apply_schema_plan`) | The pool's own writer-mutex connection (`ConnectionPool::new`, before the `WriterTask` is ever spawned) | No | Exempt — runs once at boot, before any queue handle exists to route through |
32//! | Checkpointing (`checkpoint::CheckpointConnection`) | Dedicated standalone connection, opened once at task startup (ADR-091 Amendment 5, #1652) | No | Exempt by design — the whole point of that fix was moving checkpoint I/O OFF the pool writer's admission path; routing it back through the write queue would reintroduce the contention it removed |
33//! | Recovery (`walpin` beacon/sidecar bookkeeping) | None — file-level bookkeeping (PID beacons, heartbeats) alongside the database, not a SQL connection against it | No | N/A — never acquires a database writer connection |
34//! | Top-level maintenance (`VACUUM` via `execute_script_top_level`/`WriterTaskHandle::send_top_level`) | `WriterTaskHandle`, skipping the per-request `BEGIN IMMEDIATE`/`COMMIT` wrap only | Yes | Routed through the SAME single writer owner as every other queued request — only the transaction wrap is skipped, never the queue |
35//!
36//! Store constructors may run outside Tokio and temporarily cache no handle;
37//! every store request-path write refreshes through
38//! `ConnectionPool::writer_task_for_write` at execution time. Strict routing
39//! refuses a missing handle, while the explicit compatibility fallback emits
40//! its store-specific violation at the actual direct-writer seam. Runtime
41//! entity/note merges and symmetric edge updates use the same routing policy
42//! through a closed operation adapter. The strict default itself remains gated
43//! by ADR-135 F2 / ADR-136 D2 evidence.
44//!
45//! A `direct_route_violation` sink row (`timeout_sink::emit_direct_route_violation`,
46//! ADR-136 D1 gate 6c) is emitted ONLY for the first row's degrade path — a
47//! request-path write that bypassed an enabled queue. The other four
48//! rows are exempt by design and never emit that row.
49
50use rusqlite::Connection;
51use std::collections::HashMap;
52use std::panic::{catch_unwind, AssertUnwindSafe};
53use std::path::{Path, PathBuf};
54use std::sync::{Arc, Mutex, OnceLock};
55use std::time::{Duration, Instant};
56use tokio::sync::{mpsc, oneshot};
57
58use khive_storage::error::{StorageError, WriterTaskRequestState};
59
60use crate::error::SqliteError;
61use crate::pool::{ConnectionPool, WriterAcquisitionCounters};
62use crate::writer_admission_metrics::{
63 AdmissionObservation, Snapshot, Unavailable, WriterAdmissionMetrics,
64};
65
66#[path = "writer_task_labels.rs"]
67mod labels;
68
69pub(crate) use labels::{collect_statement_labels, MAX_WRITE_LABELS};
70use labels::{dedup_labels, SubmitLabels};
71
72/// Retry delays after a busy/locked `BEGIN IMMEDIATE` refusal. The operation
73/// closure remains owned by the request until one BEGIN succeeds, so these
74/// are the only retries this path may perform. Persistent contention is
75/// bounded to three total BEGIN attempts and 15 ms of explicit backoff, and
76/// the attempts together share one configured `busy_timeout` acquisition
77/// budget rather than each waiting out a full window of their own.
78const WRITER_BEGIN_RETRY_DELAYS: [Duration; 2] =
79 [Duration::from_millis(5), Duration::from_millis(10)];
80
81/// Closure signature for a write operation executed against the writer
82/// task's dedicated connection.
83///
84/// `conn` is already inside a `BEGIN IMMEDIATE` transaction opened by
85/// `run_writer_task` when this runs. The closure must issue DML (and, in
86/// later slices, named `SAVEPOINT`s) only — never a bare `BEGIN` / `COMMIT`
87/// / `ROLLBACK` — a nested bare `BEGIN IMMEDIATE` would violate SQLite's
88/// nested-transaction rule and return `SQLITE_ERROR: cannot start a
89/// transaction within a transaction` (ADR-067 lines 271-276).
90type WriteOp<R> = Box<dyn FnOnce(&Connection) -> Result<R, StorageError> + Send>;
91
92/// Latest completed writer-task span for one database, decomposed at the
93/// boundaries an operator can act on (#1849). A zero value means that phase
94/// did not run (top-level/early-failure request) or completed below the
95/// microsecond clock resolution; `total_micros` retains the full span.
96#[derive(Debug, Clone, PartialEq, Eq)]
97pub struct WriterStageObservation {
98 pub queue_wait_micros: u64,
99 pub transaction_acquire_micros: u64,
100 pub body_micros: u64,
101 pub commit_micros: u64,
102 pub total_micros: u64,
103 pub queue_depth_at_entry: u64,
104 pub observed_at_unix_ms: u64,
105 /// Distinct labels the drained request ran, in first-seen order,
106 /// deduplicated and bounded at `MAX_WRITE_LABELS`. Resolved only for a
107 /// write that crossed the slow-write threshold, so empty for every write
108 /// below it; also empty when no statement in the request carried a label
109 /// and the submit site had no name in hand — e.g. an opaque closure from
110 /// a caller with no `&'static str` operation.
111 pub labels: Vec<String>,
112 /// Distinct labels dropped past `MAX_WRITE_LABELS`, when the request
113 /// named more; `None` when nothing was dropped.
114 pub labels_truncated: Option<u64>,
115}
116
117static WRITER_STAGE_OBSERVATIONS: OnceLock<
118 Mutex<HashMap<Option<PathBuf>, WriterStageObservation>>,
119> = OnceLock::new();
120
121fn writer_stage_observations() -> &'static Mutex<HashMap<Option<PathBuf>, WriterStageObservation>> {
122 WRITER_STAGE_OBSERVATIONS.get_or_init(|| Mutex::new(HashMap::new()))
123}
124
125fn writer_db_key_from_path(path: Option<&Path>) -> Option<PathBuf> {
126 path.map(Path::to_path_buf)
127}
128
129fn writer_db_key(pool: &ConnectionPool) -> Option<PathBuf> {
130 writer_db_key_from_path(pool.canonical_path())
131}
132
133fn duration_micros(duration: Duration) -> u64 {
134 duration.as_micros().min(u128::from(u64::MAX)) as u64
135}
136
137fn observed_at_unix_ms() -> u64 {
138 std::time::SystemTime::now()
139 .duration_since(std::time::UNIX_EPOCH)
140 .map(|duration| duration.as_millis() as u64)
141 .unwrap_or(0)
142}
143
144/// Pure in-memory read of the most recently completed writer-task span for
145/// this exact backend. It acquires no SQLite connection and performs no I/O.
146pub fn last_writer_stage_observation(pool: &ConnectionPool) -> Option<WriterStageObservation> {
147 writer_stage_observations()
148 .lock()
149 .unwrap_or_else(std::sync::PoisonError::into_inner)
150 .get(&writer_db_key(pool))
151 .cloned()
152}
153
154#[cfg(test)]
155trait TestWriterStageClock: Send + Sync {
156 fn now(&self) -> Instant;
157 fn at_commit(&self);
158}
159
160struct WriteTelemetry {
161 #[cfg(test)]
162 test_clock: Option<std::sync::Arc<dyn TestWriterStageClock>>,
163 backend_key: Option<PathBuf>,
164 db: String,
165 submitted_at: Instant,
166 queue_depth_at_entry: usize,
167 slow_write_threshold: Option<Duration>,
168 labels: SubmitLabels,
169}
170
171impl WriteTelemetry {
172 fn new(
173 backend_key: Option<PathBuf>,
174 db: String,
175 queue_depth_at_entry: usize,
176 slow_write_threshold: Option<Duration>,
177 labels: SubmitLabels,
178 ) -> Self {
179 Self {
180 #[cfg(test)]
181 test_clock: None,
182 backend_key,
183 db,
184 submitted_at: Instant::now(),
185 queue_depth_at_entry,
186 slow_write_threshold,
187 labels,
188 }
189 }
190
191 fn queue_wait(&self) -> Duration {
192 self.submitted_at.elapsed()
193 }
194
195 /// The labels named on this request, bounded to [`MAX_WRITE_LABELS`]
196 /// plus the count of distinct labels dropped. Computed only on the slow
197 /// path, since only [`Self::finish`] calls it: the fast path never turns
198 /// a [`SubmitLabels::Site`] name into an allocation.
199 fn resolve_labels(&self) -> (Vec<String>, Option<u64>) {
200 match &self.labels {
201 SubmitLabels::None => (Vec::new(), None),
202 SubmitLabels::Site(site) => (vec![(*site).to_owned()], None),
203 SubmitLabels::Statements(labels) => {
204 if labels.len() <= MAX_WRITE_LABELS {
205 (labels.clone(), None)
206 } else {
207 let dropped = (labels.len() - MAX_WRITE_LABELS) as u64;
208 (labels[..MAX_WRITE_LABELS].to_vec(), Some(dropped))
209 }
210 }
211 }
212 }
213
214 fn finish(
215 self,
216 queue_wait: Duration,
217 transaction_acquire: Duration,
218 body: Duration,
219 commit: Duration,
220 ) {
221 let total = self.submitted_at.elapsed();
222 let slow = self
223 .slow_write_threshold
224 .is_some_and(|threshold| total >= threshold);
225 // Labels are resolved only for a write that crossed the slow
226 // threshold, so a fast write never turns a site name into an
227 // allocation; its observation carries no labels.
228 let (labels, labels_truncated) = if slow {
229 self.resolve_labels()
230 } else {
231 (Vec::new(), None)
232 };
233 let observation = WriterStageObservation {
234 queue_wait_micros: duration_micros(queue_wait),
235 transaction_acquire_micros: duration_micros(transaction_acquire),
236 body_micros: duration_micros(body),
237 commit_micros: duration_micros(commit),
238 total_micros: duration_micros(total),
239 queue_depth_at_entry: self.queue_depth_at_entry as u64,
240 observed_at_unix_ms: observed_at_unix_ms(),
241 labels,
242 labels_truncated,
243 };
244 writer_stage_observations()
245 .lock()
246 .unwrap_or_else(std::sync::PoisonError::into_inner)
247 .insert(self.backend_key, observation.clone());
248
249 if slow {
250 crate::timeout_sink::emit_slow_write(&self.db, &observation);
251 }
252 }
253}
254
255/// One write request awaiting execution by the writer task.
256///
257/// Carries a typed closure and a typed oneshot reply so that the concrete
258/// return type `R` (e.g. `BatchWriteSummary`) is preserved end to end,
259/// while [`AnyWriteRequest`] lets the drain loop hold heterogeneous
260/// requests in one homogeneous channel.
261///
262/// `top_level` (ADR-067 Component A): when `true`,
263/// the drain loop runs this request's operation WITHOUT wrapping it in a
264/// `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` — still serialized through the
265/// single writer owner (only one request drains at a time regardless of
266/// this flag), but with the transaction wrap skipped entirely. Exists for
267/// statements SQLite forbids inside any open transaction (e.g. `VACUUM`);
268/// see [`WriterTaskHandle::send_top_level`].
269pub struct WriteRequest<R: Send + 'static> {
270 op: WriteOp<R>,
271 reply: oneshot::Sender<Result<R, StorageError>>,
272 top_level: bool,
273 /// Only the typed checkpoint entry point may bypass disk admission.
274 checkpoint_bypass: bool,
275 vacuum_copy_headroom: bool,
276 /// The lease class of the issuing thread's scope when the request was
277 /// queued, applied on the writer thread when it takes the volume lease.
278 lease_class: crate::disk_guard::WriteClassContext,
279 telemetry: WriteTelemetry,
280 admission: Option<AdmissionObservation>,
281}
282
283mod sealed {
284 /// Restricts [`super::AnyWriteRequest`] to implementations defined in
285 /// this module — only [`super::WriteRequest<R>`] implements it — and
286 /// carries the drain loop's internal terminal-state reporting methods
287 /// without changing the public execution-method signatures.
288 pub trait Sealed {
289 fn start_execution(&mut self);
290
291 fn execute_and_reply_reporting_terminal(
292 self: Box<Self>,
293 conn: &rusqlite::Connection,
294 tx_span: Option<khive_storage::tx_registry::TxHandle>,
295 queue_wait: std::time::Duration,
296 transaction_acquire: std::time::Duration,
297 ) -> Option<khive_storage::error::WriterTaskRequestState>;
298
299 fn execute_and_reply_top_level_reporting_terminal(
300 self: Box<Self>,
301 conn: &rusqlite::Connection,
302 queue_wait: std::time::Duration,
303 ) -> Option<khive_storage::error::WriterTaskRequestState>;
304
305 fn reply_error_after_begin(
306 self: Box<Self>,
307 err: khive_storage::error::StorageError,
308 queue_wait: std::time::Duration,
309 transaction_acquire: std::time::Duration,
310 );
311 }
312}
313
314/// Type-erased write request the writer task's drain loop can hold in a
315/// homogeneous channel (`mpsc::Sender<Box<dyn AnyWriteRequest + Send>>`),
316/// while each concrete [`WriteRequest<R>`] still carries its own typed
317/// reply. Sealed: only this module may implement it (ADR-067 lines
318/// 210-212).
319pub trait AnyWriteRequest: sealed::Sealed + Send {
320 /// Runs this request's operation against `conn`, commits or rolls back
321 /// the enclosing transaction based on the outcome, and sends the
322 /// (possibly commit-failure-adjusted) result to the request's oneshot
323 /// reply channel.
324 ///
325 /// `conn` must already be inside a successfully-opened `BEGIN IMMEDIATE`
326 /// transaction opened by the caller (`run_writer_task`) — this method
327 /// issues only `COMMIT` / `ROLLBACK`, never `BEGIN`, so `run_writer_task`
328 /// remains the sole issuer of `BEGIN IMMEDIATE` (ADR-067 Component A).
329 /// Callers must use [`Self::reply_error`] instead when the enclosing
330 /// `BEGIN IMMEDIATE` itself failed — this method must not be invoked in
331 /// that case.
332 fn execute_and_reply(self: Box<Self>, conn: &Connection);
333
334 /// Runs this request's operation directly against `conn` — no
335 /// transaction wrap, no `COMMIT`/`ROLLBACK` — and sends the result to
336 /// the request's oneshot reply channel.
337 ///
338 /// Used only for [`Self::is_top_level`] requests: the drain loop calls
339 /// this INSTEAD of `execute_and_reply` for such requests, skipping
340 /// `BEGIN IMMEDIATE` entirely so a statement that must run outside any
341 /// transaction (e.g. `VACUUM`) can still be serialized through the
342 /// single writer owner.
343 fn execute_and_reply_top_level(self: Box<Self>, conn: &Connection);
344
345 /// Replies with `err` without running this request's operation or
346 /// touching `conn`.
347 ///
348 /// Used when the enclosing `BEGIN IMMEDIATE` failed (for example,
349 /// `SQLITE_BUSY` from lock contention with an unmigrated writer path
350 /// still holding the pool's writer mutex — reachable while only
351 /// `entity.rs` is routed through this channel). Running the operation
352 /// anyway would execute its DML against `conn` in autocommit mode,
353 /// landing partial writes for a request the caller is told failed.
354 /// Skipping the operation entirely keeps "the caller got an error" and
355 /// "no rows landed" true together.
356 fn reply_error(self: Box<Self>, err: StorageError);
357
358 /// `true` if the drain loop must run this request via
359 /// [`Self::execute_and_reply_top_level`] (no transaction wrap) instead
360 /// of [`Self::execute_and_reply`] (wrapped in `BEGIN IMMEDIATE`).
361 fn is_top_level(&self) -> bool;
362
363 fn is_checkpoint_bypass(&self) -> bool;
364
365 fn needs_vacuum_headroom(&self) -> bool;
366
367 /// The issuing thread's lease-class context, captured when it was queued.
368 fn lease_class(&self) -> crate::disk_guard::WriteClassContext;
369
370 /// Time from the caller constructing this request (before bounded-channel
371 /// admission) until the writer task dequeued it.
372 fn queue_wait(&self) -> Duration;
373}
374
375#[derive(Debug, Clone, Copy, PartialEq, Eq)]
376enum RollbackDisposition {
377 RolledBack,
378 SideEffectsUnknown,
379}
380
381/// Roll back a failed wrapped request and verify that the connection really
382/// returned to autocommit mode before it can serve another request.
383fn rollback_after_failure(conn: &Connection, failure_context: &'static str) -> RollbackDisposition {
384 match conn.execute_batch("ROLLBACK") {
385 Ok(()) if conn.is_autocommit() => RollbackDisposition::RolledBack,
386 Ok(()) => {
387 tracing::error!(
388 failure_context,
389 "writer transaction: ROLLBACK returned success but the connection is still in a \
390 transaction; request side effects are unknown"
391 );
392 RollbackDisposition::SideEffectsUnknown
393 }
394 Err(rollback_error) => {
395 tracing::error!(
396 error = %rollback_error,
397 failure_context,
398 "writer transaction: rollback after request failure failed; request side effects are \
399 unknown"
400 );
401 RollbackDisposition::SideEffectsUnknown
402 }
403 }
404}
405
406/// Execute an operation inside an already-open transaction and apply the
407/// shared commit, rollback, panic, and autocommit verification rules.
408///
409/// This worker/owned adapter catches callback panics, attempts rollback, and
410/// returns a typed terminal outcome. In contrast, [`crate::pool::WriterGuard::transaction`]
411/// propagates callback panics and settles its owner during unwinding.
412pub(crate) fn execute_wrapped_transaction<R, F>(
413 conn: &Connection,
414 commit_operation: &'static str,
415 operation: F,
416) -> (Result<R, StorageError>, Option<WriterTaskRequestState>)
417where
418 F: FnOnce(&Connection) -> Result<R, StorageError>,
419{
420 let profiled = execute_wrapped_transaction_profiled(
421 conn,
422 commit_operation,
423 None,
424 false,
425 operation,
426 #[cfg(test)]
427 None,
428 );
429 (profiled.result, profiled.terminal_state)
430}
431
432/// The standalone SQL bridge shares settlement rules while retaining its
433/// native commit error source and timeout/full observation site.
434pub(crate) fn execute_wrapped_sql_bridge_transaction<R, F>(
435 conn: &Connection,
436 commit_operation: &'static str,
437 db: &str,
438 operation: F,
439) -> (Result<R, StorageError>, Option<WriterTaskRequestState>)
440where
441 F: FnOnce(&Connection) -> Result<R, StorageError>,
442{
443 let profiled = execute_wrapped_transaction_profiled(
444 conn,
445 commit_operation,
446 Some(db),
447 true,
448 operation,
449 #[cfg(test)]
450 None,
451 );
452 (profiled.result, profiled.terminal_state)
453}
454
455struct ProfiledWrappedTransaction<R> {
456 result: Result<R, StorageError>,
457 terminal_state: Option<WriterTaskRequestState>,
458 body: Duration,
459 commit: Duration,
460}
461
462fn execute_wrapped_transaction_profiled<R, F>(
463 conn: &Connection,
464 commit_operation: &'static str,
465 db: Option<&str>,
466 direct_sql_bridge: bool,
467 operation: F,
468 #[cfg(test)] test_clock: Option<&dyn TestWriterStageClock>,
469) -> ProfiledWrappedTransaction<R>
470where
471 F: FnOnce(&Connection) -> Result<R, StorageError>,
472{
473 let body_started = Instant::now();
474 #[cfg(test)]
475 let body_started = test_clock.map_or(body_started, TestWriterStageClock::now);
476 // Keep panic-to-terminal conversion local to this adapter; the public
477 // WriterGuard transaction intentionally propagates the callback's unwind.
478 let operation_outcome = catch_unwind(AssertUnwindSafe(|| {
479 operation(conn).map_err(crate::error::statement_failure)
480 }));
481 #[cfg(not(test))]
482 let body = body_started.elapsed();
483 #[cfg(test)]
484 let body = test_clock.map_or_else(
485 || body_started.elapsed(),
486 |clock| clock.now().duration_since(body_started),
487 );
488
489 match operation_outcome {
490 Ok(Ok(value)) => {
491 let commit_started = Instant::now();
492 #[cfg(test)]
493 let commit_started = test_clock.map_or(commit_started, TestWriterStageClock::now);
494 #[cfg(test)]
495 if let Some(clock) = test_clock {
496 clock.at_commit();
497 }
498 let commit_outcome = conn.execute_batch("COMMIT");
499 #[cfg(not(test))]
500 let commit = commit_started.elapsed();
501 #[cfg(test)]
502 let commit = test_clock.map_or_else(
503 || commit_started.elapsed(),
504 |clock| clock.now().duration_since(commit_started),
505 );
506 match commit_outcome {
507 Ok(()) if conn.is_autocommit() => ProfiledWrappedTransaction {
508 result: Ok(value),
509 terminal_state: None,
510 body,
511 commit,
512 },
513 Ok(()) => {
514 tracing::error!(
515 "writer transaction: COMMIT returned success but the connection is still in \
516 a transaction; request side effects are unknown"
517 );
518 let request_state = WriterTaskRequestState::SideEffectsUnknown;
519 ProfiledWrappedTransaction {
520 result: Err(writer_task_terminated(request_state)),
521 terminal_state: Some(request_state),
522 body,
523 commit,
524 }
525 }
526 Err(commit_error) => {
527 if let Some(db) = db {
528 if direct_sql_bridge {
529 crate::timeout_sink::maybe_emit_busy(
530 db,
531 crate::timeout_sink::Site::StandaloneSqlBridge,
532 &commit_error,
533 );
534 } else {
535 crate::timeout_sink::maybe_emit_sqlite_full(db, &commit_error);
536 }
537 }
538 match rollback_after_failure(conn, "commit failure") {
539 RollbackDisposition::RolledBack => ProfiledWrappedTransaction {
540 result: Err(StorageError::WriterTaskRequestFailed {
541 request_state: WriterTaskRequestState::TransactionRolledBack,
542 source: Box::new({
543 let failure = crate::error::native_write_failure(
544 &commit_error,
545 khive_storage::error::SqliteWriteStage::Commit,
546 );
547 let error = if direct_sql_bridge {
548 StorageError::driver(
549 khive_storage::StorageCapability::Sql,
550 commit_operation,
551 commit_error,
552 )
553 } else {
554 StorageError::Pool {
555 operation: commit_operation.into(),
556 message: commit_error.to_string(),
557 }
558 };
559 match failure {
560 Some(failure) => error.with_sqlite_write_failure(failure),
561 None => error,
562 }
563 }),
564 }),
565 terminal_state: None,
566 body,
567 commit,
568 },
569 RollbackDisposition::SideEffectsUnknown => {
570 let request_state = WriterTaskRequestState::SideEffectsUnknown;
571 ProfiledWrappedTransaction {
572 result: Err(writer_task_terminated_with_cause(
573 request_state,
574 &commit_error,
575 khive_storage::error::SqliteWriteStage::Commit,
576 )),
577 terminal_state: Some(request_state),
578 body,
579 commit,
580 }
581 }
582 }
583 }
584 }
585 }
586 Ok(Err(operation_error)) => {
587 match rollback_after_failure(conn, "request operation failure") {
588 RollbackDisposition::RolledBack => ProfiledWrappedTransaction {
589 result: Err(StorageError::WriterTaskRequestFailed {
590 request_state: WriterTaskRequestState::TransactionRolledBack,
591 source: Box::new(operation_error),
592 }),
593 terminal_state: None,
594 body,
595 commit: Duration::ZERO,
596 },
597 RollbackDisposition::SideEffectsUnknown => {
598 // SQLite may have already rolled back a failed transaction,
599 // leaving no transaction for the explicit ROLLBACK.
600 // Escalate the original cause once; retain native FULL evidence below.
601 if let Some(db) = db {
602 crate::timeout_sink::maybe_emit_sqlite_full(db, &operation_error);
603 }
604 let request_state = WriterTaskRequestState::SideEffectsUnknown;
605 ProfiledWrappedTransaction {
606 result: Err(writer_task_terminated_with_cause(
607 request_state,
608 &operation_error,
609 khive_storage::error::SqliteWriteStage::Statement,
610 )),
611 terminal_state: Some(request_state),
612 body,
613 commit: Duration::ZERO,
614 }
615 }
616 }
617 }
618 Err(_panic_payload) => {
619 let request_state = match rollback_after_failure(conn, "request panic") {
620 RollbackDisposition::RolledBack => WriterTaskRequestState::TransactionRolledBack,
621 RollbackDisposition::SideEffectsUnknown => {
622 WriterTaskRequestState::SideEffectsUnknown
623 }
624 };
625 ProfiledWrappedTransaction {
626 result: Err(writer_task_terminated(request_state)),
627 terminal_state: Some(request_state),
628 body,
629 commit: Duration::ZERO,
630 }
631 }
632 }
633}
634
635fn reply_with_admission<R>(
636 reply: oneshot::Sender<Result<R, StorageError>>,
637 mut admission: Option<AdmissionObservation>,
638 result: Result<R, StorageError>,
639) {
640 if let Some(observation) = admission.as_mut() {
641 observation.reply_attempt();
642 }
643 let _ = reply.send(result);
644}
645
646impl<R: Send + 'static> sealed::Sealed for WriteRequest<R> {
647 fn start_execution(&mut self) {
648 if let Some(observation) = self.admission.as_mut() {
649 observation.start_execution();
650 }
651 }
652
653 fn execute_and_reply_reporting_terminal(
654 self: Box<Self>,
655 conn: &Connection,
656 tx_span: Option<khive_storage::tx_registry::TxHandle>,
657 queue_wait: Duration,
658 transaction_acquire: Duration,
659 ) -> Option<WriterTaskRequestState> {
660 // Keep the typed reply sender outside the unwind boundary. Calling
661 // `(self.op)(conn)` directly would drop `self.reply` while unwinding,
662 // leaving the active caller with only an untyped RecvError.
663 let WriteRequest {
664 op,
665 reply,
666 telemetry,
667 admission,
668 ..
669 } = *self;
670 let profiled = execute_wrapped_transaction_profiled(
671 conn,
672 "writer_task_commit",
673 Some(&telemetry.db),
674 false,
675 op,
676 #[cfg(test)]
677 telemetry.test_clock.as_deref(),
678 );
679 if let Err(error) = &profiled.result {
680 crate::timeout_sink::maybe_emit_sqlite_full(&telemetry.db, error);
681 }
682 // The reply wake can make the caller immediately observe the
683 // committed/error result. Deregister the transaction span first so
684 // tx_registry continues to mean "currently open SQL transaction",
685 // never "a transaction whose caller has already resumed" (#1790).
686 drop(tx_span);
687 telemetry.finish(
688 queue_wait,
689 transaction_acquire,
690 profiled.body,
691 profiled.commit,
692 );
693 // The receiver may already be gone (caller dropped its future) —
694 // that is not this task's problem to report.
695 reply_with_admission(reply, admission, profiled.result);
696 profiled.terminal_state
697 }
698
699 fn execute_and_reply_top_level_reporting_terminal(
700 self: Box<Self>,
701 conn: &Connection,
702 queue_wait: Duration,
703 ) -> Option<WriterTaskRequestState> {
704 let WriteRequest {
705 op,
706 reply,
707 telemetry,
708 admission,
709 ..
710 } = *self;
711 let body_started = Instant::now();
712 let outcome = catch_unwind(AssertUnwindSafe(|| {
713 op(conn).map_err(crate::error::statement_failure)
714 }));
715 let body = body_started.elapsed();
716 let telemetry_db = telemetry.db.clone();
717 telemetry.finish(queue_wait, Duration::ZERO, body, Duration::ZERO);
718 match outcome {
719 Ok(outcome) if conn.is_autocommit() => {
720 // No COMMIT/ROLLBACK here: this request explicitly did not
721 // open a transaction, so there is nothing to close.
722 if let Err(error) = &outcome {
723 crate::timeout_sink::maybe_emit_sqlite_full(&telemetry_db, error);
724 }
725 reply_with_admission(reply, admission, outcome);
726 None
727 }
728 Ok(outcome) => {
729 tracing::error!(
730 "writer task: top-level request returned with an open transaction; request \
731 side effects are unknown"
732 );
733 let request_state = WriterTaskRequestState::SideEffectsUnknown;
734 let error = match outcome {
735 Err(error) => writer_task_terminated_with_cause(
736 request_state,
737 &error,
738 khive_storage::error::SqliteWriteStage::Statement,
739 ),
740 Ok(_) => writer_task_terminated(request_state),
741 };
742 reply_with_admission(reply, admission, Err(error));
743 Some(request_state)
744 }
745 Err(_panic_payload) => {
746 // Statements completed before a top-level panic may already
747 // have autocommitted. Report the ambiguity; never invent a
748 // rollback for a request that opened no transaction.
749 let request_state = WriterTaskRequestState::SideEffectsUnknown;
750 reply_with_admission(reply, admission, Err(writer_task_terminated(request_state)));
751 Some(request_state)
752 }
753 }
754 }
755
756 fn reply_error_after_begin(
757 self: Box<Self>,
758 err: StorageError,
759 queue_wait: Duration,
760 transaction_acquire: Duration,
761 ) {
762 let WriteRequest {
763 reply,
764 telemetry,
765 admission,
766 ..
767 } = *self;
768 telemetry.finish(
769 queue_wait,
770 transaction_acquire,
771 Duration::ZERO,
772 Duration::ZERO,
773 );
774 reply_with_admission(reply, admission, Err(err));
775 }
776}
777
778impl<R: Send + 'static> AnyWriteRequest for WriteRequest<R> {
779 fn execute_and_reply(mut self: Box<Self>, conn: &Connection) {
780 let queue_wait = self.queue_wait();
781 sealed::Sealed::start_execution(self.as_mut());
782 let _ = sealed::Sealed::execute_and_reply_reporting_terminal(
783 self,
784 conn,
785 None,
786 queue_wait,
787 Duration::ZERO,
788 );
789 }
790
791 fn execute_and_reply_top_level(mut self: Box<Self>, conn: &Connection) {
792 let queue_wait = self.queue_wait();
793 sealed::Sealed::start_execution(self.as_mut());
794 let _ =
795 sealed::Sealed::execute_and_reply_top_level_reporting_terminal(self, conn, queue_wait);
796 }
797
798 fn reply_error(self: Box<Self>, err: StorageError) {
799 let queue_wait = self.queue_wait();
800 sealed::Sealed::reply_error_after_begin(self, err, queue_wait, Duration::ZERO);
801 }
802
803 fn is_top_level(&self) -> bool {
804 self.top_level
805 }
806
807 fn is_checkpoint_bypass(&self) -> bool {
808 self.checkpoint_bypass
809 }
810
811 fn needs_vacuum_headroom(&self) -> bool {
812 self.vacuum_copy_headroom
813 }
814
815 fn lease_class(&self) -> crate::disk_guard::WriteClassContext {
816 self.lease_class
817 }
818
819 fn queue_wait(&self) -> Duration {
820 self.telemetry.queue_wait()
821 }
822}
823
824fn writer_task_terminated(request_state: WriterTaskRequestState) -> StorageError {
825 StorageError::writer_task_terminated(request_state)
826}
827
828fn writer_task_terminated_with_cause(
829 request_state: WriterTaskRequestState,
830 error: &(dyn std::error::Error + 'static),
831 stage: khive_storage::error::SqliteWriteStage,
832) -> StorageError {
833 let mut source = Some(error);
834 let mut sqlite_full_codes = None;
835 while let Some(current) = source {
836 if let Some(rusqlite::Error::SqliteFailure(code, _)) =
837 current.downcast_ref::<rusqlite::Error>()
838 {
839 if code.code == rusqlite::ErrorCode::DiskFull {
840 sqlite_full_codes = Some((code.extended_code & 0xff, code.extended_code));
841 break;
842 }
843 }
844 source = current.source();
845 }
846 // The original error was already escalated at the failing boundary.
847 // A source-free pair preserves caller evidence without duplicating that sink event.
848 let terminal = StorageError::WriterTaskTerminated {
849 request_state,
850 sqlite_full_codes,
851 };
852 match crate::error::native_write_failure(error, stage) {
853 Some(mut failure) => {
854 failure.settlement_unknown =
855 request_state == WriterTaskRequestState::SideEffectsUnknown;
856 terminal.with_sqlite_write_failure(failure)
857 }
858 None => terminal,
859 }
860}
861
862fn writer_task_begin_error(error: rusqlite::Error, busy_timeout: Duration) -> StorageError {
863 let failure =
864 crate::error::native_write_failure(&error, khive_storage::error::SqliteWriteStage::Begin);
865 let mapped = if crate::timeout_sink::is_busy_or_locked(&error) {
866 StorageError::WriterTaskBusy {
867 timeout_ms: u64::try_from(busy_timeout.as_millis()).unwrap_or(u64::MAX),
868 }
869 } else {
870 StorageError::Pool {
871 operation: "writer_task_begin".into(),
872 message: error.to_string(),
873 }
874 };
875 match failure {
876 Some(failure) => mapped.with_sqlite_write_failure(failure),
877 None => mapped,
878 }
879}
880
881/// Sender half of the write queue. Cheaply cloneable (wraps an
882/// `mpsc::Sender`) — every migrated store that shares one writer task holds
883/// a clone of this handle.
884#[derive(Clone, Debug)]
885pub struct WriterTaskHandle {
886 tx: mpsc::Sender<Box<dyn AnyWriteRequest + Send>>,
887 /// Exact canonical backend identity used by the in-memory stage registry.
888 /// Kept separate from `db`, whose lossy display form is logging-only.
889 backend_key: Option<PathBuf>,
890 /// This handle's pool's writer-timeout sink identity (`timeout_sink::db_label`),
891 /// captured at spawn so `send_with_timeout`'s `WriteQueueFull` path can
892 /// report a `queue_saturation` sink row (ADR-136 D1 gate 6a) without
893 /// needing a `&ConnectionPool` reference.
894 db: String,
895 /// Slow-write latency bound (`timeout_sink::slow_write_threshold`),
896 /// resolved once at spawn. `None` disables slow-write rows. Captured
897 /// here rather than read per send so the caller path pays no env lookup
898 /// and tests get a deterministic value by setting the override before
899 /// spawning their own writer task.
900 slow_write_threshold: Option<std::time::Duration>,
901 /// Default enqueue-capacity deadline for [`Self::send_bounded`] /
902 /// [`Self::send_top_level_bounded`], captured from
903 /// `PoolConfig::write_admission_deadline_ms` at [`spawn`] (ADR-131
904 /// Decision 2). Bounds ONLY the wait for channel capacity, the same
905 /// boundary `send_with_timeout` already documents — never the reply wait
906 /// after acceptance (#1382).
907 ///
908 /// This is a dedicated admission authority, distinct from
909 /// `PoolConfig::checkout_timeout` (reader/pool checkout). The two used
910 /// to be conflated here before ADR-131 Decision 2 (#1382, #1643).
911 ///
912 /// ADR-131 Decision 2's outer-request-budget clamp ("when the caller's outer
913 /// request deadline leaves less time remaining than the configured
914 /// admission deadline, the admission deadline applied to that operation
915 /// is the remaining outer budget instead") is explicitly DEFERRED: no
916 /// outer request deadline is plumbed to `send_bounded` /
917 /// `send_top_level_bounded`'s call sites as of #1737, so there is no
918 /// budget to clamp against. When an outer deadline reaches this call
919 /// path, clamp here rather than faking a shorter deadline against a
920 /// nonexistent budget.
921 enqueue_timeout: std::time::Duration,
922 admission_metrics: Arc<WriterAdmissionMetrics>,
923}
924
925impl WriterTaskHandle {
926 /// Enqueue a write operation and return the oneshot receiver its reply
927 /// will arrive on, once the request has actually been accepted onto the
928 /// channel.
929 ///
930 /// Shared by [`Self::send`] and [`Self::send_with_timeout`] so that a
931 /// caller-supplied deadline (see `send_with_timeout`) can bound ONLY
932 /// this enqueue step — never the reply-wait that follows it. Once this
933 /// returns `Ok`, the request has been accepted by the writer task and
934 /// will either run to completion or receive a typed terminal error if an
935 /// earlier request kills the task before this operation begins. The
936 /// returned receiver must be awaited without a timeout; abandoning it
937 /// here would silently drop the request's eventual result, not cancel the
938 /// request itself.
939 async fn enqueue<R, F>(
940 &self,
941 op: F,
942 ) -> Result<oneshot::Receiver<Result<R, StorageError>>, StorageError>
943 where
944 R: Send + 'static,
945 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
946 {
947 self.enqueue_inner(op, false, false, false, SubmitLabels::None)
948 .await
949 }
950
951 /// Shared enqueue path for both transaction-wrapped ([`Self::enqueue`])
952 /// and top-level ([`Self::send_top_level`]) requests — `top_level`
953 /// controls which [`AnyWriteRequest`] method the drain loop invokes.
954 /// `labels` is what the submit site knows about this request's
955 /// statements; see [`SubmitLabels`].
956 async fn enqueue_inner<R, F>(
957 &self,
958 op: F,
959 top_level: bool,
960 checkpoint_bypass: bool,
961 vacuum_copy_headroom: bool,
962 labels: SubmitLabels,
963 ) -> Result<oneshot::Receiver<Result<R, StorageError>>, StorageError>
964 where
965 R: Send + 'static,
966 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
967 {
968 let (reply_tx, reply_rx) = oneshot::channel();
969 // Normalize here (once per request) so every submit path — including
970 // the public `send_labelled` entry points a caller can hand a raw
971 // list — records distinct labels in first-seen order. Bounding stays
972 // in `resolve_labels`, which runs only on the slow path.
973 let labels = match labels {
974 SubmitLabels::Statements(labels) => {
975 SubmitLabels::Statements(dedup_labels(labels.iter().map(String::as_str)))
976 }
977 other => other,
978 };
979 let telemetry = WriteTelemetry::new(
980 self.backend_key.clone(),
981 self.db.clone(),
982 self.queue_depth(),
983 self.slow_write_threshold,
984 labels,
985 );
986 let mut request = Box::new(WriteRequest {
987 op: Box::new(op),
988 reply: reply_tx,
989 top_level,
990 checkpoint_bypass,
991 vacuum_copy_headroom,
992 lease_class: crate::disk_guard::WriteClassContext::capture(),
993 telemetry,
994 admission: None,
995 });
996 request.admission = Some(self.admission_metrics.offer());
997 let permit = self
998 .tx
999 .reserve()
1000 .await
1001 .map_err(|_| writer_task_terminated(WriterTaskRequestState::NotStarted))?;
1002 if let Some(observation) = request.admission.as_mut() {
1003 observation.accepted();
1004 }
1005 permit.send(request);
1006
1007 Ok(reply_rx)
1008 }
1009
1010 /// Send a write operation to the writer task and await its typed reply.
1011 ///
1012 /// Backpressure: this suspends on the channel's `send().await` when the
1013 /// bounded queue is full (ADR-067 "Channel capacity and queue-full
1014 /// policy") — there is no `try_send` escape hatch. Callers that need a
1015 /// deadline on that wait should use [`Self::send_with_timeout`] instead.
1016 pub async fn send<R, F>(&self, op: F) -> Result<R, StorageError>
1017 where
1018 R: Send + 'static,
1019 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1020 {
1021 let reply_rx = self.enqueue(op).await?;
1022 reply_rx
1023 .await
1024 .map_err(|_| writer_task_terminated(WriterTaskRequestState::SideEffectsUnknown))?
1025 }
1026
1027 /// Like [`Self::send`], but bounds the wait for the bounded channel to
1028 /// free capacity with `timeout`.
1029 ///
1030 /// The timeout applies ONLY to enqueueing the request (the channel
1031 /// `send().await` that can suspend on a full queue) — never to waiting
1032 /// for the writer task's reply once the request has been accepted.
1033 /// `StorageError::WriteQueueFull` means exactly "the bounded channel was
1034 /// full and this request was never accepted"; it must never be returned
1035 /// for a request that was accepted and is still executing (or already
1036 /// committed) by the time `timeout` elapses — that would misreport a
1037 /// slow op or a lock wait as a queue-capacity failure, and could tell a
1038 /// caller a write failed when it actually landed. ADR-067's queue-full
1039 /// policy has no immediate-error `try_send` path — only this caller-side
1040 /// deadline on the enqueue step.
1041 pub async fn send_with_timeout<R, F>(
1042 &self,
1043 op: F,
1044 timeout: std::time::Duration,
1045 ) -> Result<R, StorageError>
1046 where
1047 R: Send + 'static,
1048 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1049 {
1050 self.send_with_timeout_labelled(op, timeout, SubmitLabels::None)
1051 .await
1052 }
1053
1054 /// Shared body of [`Self::send_with_timeout`] and its labelled variants.
1055 /// `labels` is carried onto the request's writer-stage observation and
1056 /// `slow_write` row; see [`SubmitLabels`].
1057 async fn send_with_timeout_labelled<R, F>(
1058 &self,
1059 op: F,
1060 timeout: std::time::Duration,
1061 labels: SubmitLabels,
1062 ) -> Result<R, StorageError>
1063 where
1064 R: Send + 'static,
1065 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1066 {
1067 let reply_rx = match tokio::time::timeout(
1068 timeout,
1069 self.enqueue_inner(op, false, false, false, labels),
1070 )
1071 .await
1072 {
1073 Ok(Ok(reply_rx)) => reply_rx,
1074 Ok(Err(e)) => return Err(e),
1075 Err(_elapsed) => {
1076 let timeout_ms = timeout.as_millis() as u64;
1077 self.admission_metrics.record_capacity_deadline();
1078 crate::timeout_sink::emit_queue_saturation(&self.db, timeout_ms);
1079 return Err(StorageError::WriteQueueFull { timeout_ms });
1080 }
1081 };
1082
1083 reply_rx
1084 .await
1085 .map_err(|_| writer_task_terminated(WriterTaskRequestState::SideEffectsUnknown))?
1086 }
1087
1088 /// Like [`Self::send`], but bounds the enqueue-capacity wait with this
1089 /// handle's configured `enqueue_timeout`
1090 /// (`PoolConfig::write_admission_deadline_ms` at spawn time, ADR-131
1091 /// Decision 2) instead of waiting indefinitely (#1382).
1092 ///
1093 /// Once the request is accepted onto the channel, the reply wait is
1094 /// unbounded by this method, identical to [`Self::send`] — this bounds
1095 /// only queue-capacity admission, never SQLite execution or reply
1096 /// latency. Callers that need a non-default deadline should use
1097 /// [`Self::send_with_timeout`] directly.
1098 pub async fn send_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1099 where
1100 R: Send + 'static,
1101 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1102 {
1103 self.send_with_timeout(op, self.enqueue_timeout).await
1104 }
1105
1106 /// Send a write operation that MUST run outside any open transaction
1107 /// (e.g. `VACUUM`, which SQLite forbids inside `BEGIN`/`COMMIT`) and
1108 /// await its typed reply.
1109 ///
1110 /// Still serialized through the same single writer owner as
1111 /// [`Self::send`] — the request goes through the identical bounded
1112 /// channel and drain loop, one request at a time — but the drain loop
1113 /// skips the per-request `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` wrap
1114 /// entirely for this request (ADR-067 Component A). The single-writer
1115 /// guarantee is preserved; only
1116 /// the transaction wrap is skipped.
1117 pub async fn send_top_level<R, F>(&self, op: F) -> Result<R, StorageError>
1118 where
1119 R: Send + 'static,
1120 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1121 {
1122 let reply_rx = self
1123 .enqueue_inner(op, true, false, false, SubmitLabels::None)
1124 .await?;
1125 reply_rx
1126 .await
1127 .map_err(|_| writer_task_terminated(WriterTaskRequestState::SideEffectsUnknown))?
1128 }
1129
1130 /// Like [`Self::send_top_level`], but bounds the enqueue-capacity wait
1131 /// with this handle's configured `enqueue_timeout`, mirroring
1132 /// [`Self::send_bounded`] for top-level (transaction-skipping) requests
1133 /// (#1382).
1134 pub async fn send_top_level_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1135 where
1136 R: Send + 'static,
1137 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1138 {
1139 self.send_top_level_bounded_inner(op, false, false, SubmitLabels::None)
1140 .await
1141 }
1142
1143 /// Checkpoint-only top-level dispatch. It remains serialized by the
1144 /// writer task but never waits for the capacity lease or floor probe.
1145 pub(crate) async fn send_checkpoint_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1146 where
1147 R: Send + 'static,
1148 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1149 {
1150 self.send_top_level_bounded_inner(op, true, false, SubmitLabels::Site("wal_checkpoint"))
1151 .await
1152 }
1153
1154 /// Typed VACUUM dispatch with a copy-sized metadata estimate at dequeue.
1155 pub(crate) async fn send_vacuum_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1156 where
1157 R: Send + 'static,
1158 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1159 {
1160 self.send_top_level_bounded_inner(op, false, true, SubmitLabels::Site("vacuum"))
1161 .await
1162 }
1163
1164 async fn send_top_level_bounded_inner<R, F>(
1165 &self,
1166 op: F,
1167 checkpoint_bypass: bool,
1168 vacuum_copy_headroom: bool,
1169 labels: SubmitLabels,
1170 ) -> Result<R, StorageError>
1171 where
1172 R: Send + 'static,
1173 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1174 {
1175 let reply_rx = match tokio::time::timeout(
1176 self.enqueue_timeout,
1177 self.enqueue_inner(op, true, checkpoint_bypass, vacuum_copy_headroom, labels),
1178 )
1179 .await
1180 {
1181 Ok(Ok(reply_rx)) => reply_rx,
1182 Ok(Err(e)) => return Err(e),
1183 Err(_elapsed) => {
1184 let timeout_ms = self.enqueue_timeout.as_millis() as u64;
1185 self.admission_metrics.record_capacity_deadline();
1186 crate::timeout_sink::emit_queue_saturation(&self.db, timeout_ms);
1187 return Err(StorageError::WriteQueueFull { timeout_ms });
1188 }
1189 };
1190
1191 reply_rx
1192 .await
1193 .map_err(|_| writer_task_terminated(WriterTaskRequestState::SideEffectsUnknown))?
1194 }
1195
1196 /// Current write-queue backlog depth: requests enqueued but not yet
1197 /// accepted by the writer task's drain loop.
1198 ///
1199 /// Reads `mpsc::Sender::max_capacity() - capacity()`, so it is a
1200 /// point-in-time snapshot racy under concurrent senders/the drain loop
1201 /// draining concurrently — acceptable for a monitoring gauge (the
1202 /// load/perf harness metrics read-surface), never used for any correctness
1203 /// decision.
1204 pub fn queue_depth(&self) -> usize {
1205 self.tx.max_capacity() - self.tx.capacity()
1206 }
1207
1208 /// The bounded channel's configured capacity
1209 /// (`PoolConfig::write_queue_capacity`).
1210 pub fn capacity(&self) -> usize {
1211 self.tx.max_capacity()
1212 }
1213
1214 pub(crate) fn admission_snapshot(&self) -> Result<Snapshot, Unavailable> {
1215 self.admission_metrics.snapshot()
1216 }
1217}
1218
1219/// Spawn the write-owner task (ADR-067 Component A) on the current Tokio
1220/// runtime.
1221///
1222/// Opens a dedicated standalone writer connection independent of the pool's
1223/// Mutex-guarded `writer()` connection used by unmigrated paths. That one-time
1224/// infrastructure open is uncounted; every dequeued top-level request or
1225/// successful `BEGIN IMMEDIATE` increments the writer-task acquisition class.
1226/// Returns the cloneable [`WriterTaskHandle`] sender half. The task normally
1227/// runs until every handle clone is dropped and the channel closes; a request
1228/// panic, failed rollback, or poisoned connection puts it into the permanent
1229/// terminal state documented below.
1230///
1231/// # Terminal settlement
1232/// Retiring an unsettled writer, including when its blocking owner unwinds,
1233/// releases the volume lease only after cleanup restored autocommit or the
1234/// connection closed. If neither is possible, path, volume, and errors are
1235/// reported to stderr and tracing and the pool is poisoned: that request
1236/// reports [`SqliteError::WriterSettlementUnknown`] and every later write is
1237/// refused with [`SqliteError::WriterPoisoned`] before it starts.
1238///
1239/// `capacity` bounds the channel (`PoolConfig::write_queue_capacity` /
1240/// `KHIVE_WRITE_QUEUE_CAPACITY`, ADR-067 recommends 256).
1241///
1242/// # Errors
1243/// Must be called from within a Tokio runtime context (calls
1244/// `tokio::spawn`). Returns an error if the pool cannot open a standalone
1245/// writer connection (e.g. an in-memory pool has no standalone-connection
1246/// support). See `crates/khive-db/docs/api/writer-task.md` for the
1247/// migration-slice scope this commits per `BEGIN IMMEDIATE`.
1248pub fn spawn(pool: &ConnectionPool, capacity: usize) -> Result<WriterTaskHandle, SqliteError> {
1249 pool.spawn_writer_task(capacity)
1250}
1251
1252/// Consume a verified lifetime connection inside its admission-owning task.
1253/// Only the pool's private connection factory opens that connection.
1254pub(crate) fn spawn_with_connection(
1255 pool: &ConnectionPool,
1256 conn: Connection,
1257 capacity: usize,
1258) -> Result<WriterTaskHandle, SqliteError> {
1259 // The lifetime connection is infrastructure, not one acquisition per
1260 // write. Each dequeued request is counted below at the task's actual
1261 // ownership boundary instead.
1262 let acquisition_counters = pool.writer_acquisition_counters();
1263 let write_admission = pool.write_admission();
1264 let busy_timeout = pool.config().busy_timeout;
1265 let origin = pool.origin();
1266 let backend_key = writer_db_key(pool);
1267 let db = crate::timeout_sink::db_label(pool);
1268 let (tx, rx) = mpsc::channel(capacity.max(1));
1269 let join = tokio::spawn(run_writer_task(
1270 (conn, pool.timeout_sink_writer_lease()),
1271 rx,
1272 origin,
1273 db.clone(),
1274 acquisition_counters,
1275 write_admission,
1276 busy_timeout,
1277 ));
1278 // Stored on the pool (not returned) so the handle's clone-and-share
1279 // contract stays untouched; see ConnectionPool::take_writer_task_join
1280 // for who awaits it and why.
1281 pool.set_writer_task_join(join);
1282 Ok(WriterTaskHandle {
1283 tx,
1284 backend_key,
1285 db,
1286 slow_write_threshold: crate::timeout_sink::slow_write_threshold(),
1287 enqueue_timeout: std::time::Duration::from_millis(
1288 pool.config().write_admission_deadline_ms,
1289 ),
1290 admission_metrics: WriterAdmissionMetrics::new(),
1291 })
1292}
1293
1294/// Permanently close admission, then reply to every request that was already
1295/// accepted into the bounded channel without invoking its operation closure.
1296///
1297/// Closing before draining is load-bearing: draining an open receiver would
1298/// wait forever while [`WriterTaskHandle`] clones still exist, while dropping
1299/// the receiver immediately would discard buffered requests and their typed
1300/// reply senders.
1301async fn close_and_fail_queued_requests(rx: &mut mpsc::Receiver<Box<dyn AnyWriteRequest + Send>>) {
1302 rx.close();
1303 while let Some(request) = rx.recv().await {
1304 request.reply_error(writer_task_terminated(WriterTaskRequestState::NotStarted));
1305 }
1306}
1307
1308/// Acquire the request transaction without multiplying its busy-timeout budget.
1309/// The setter is supplied so tests can fail SQLite's timeout update while still
1310/// executing real BEGIN statements; production uses `Connection::busy_timeout`.
1311fn begin_immediate_with_retry(
1312 conn: &Connection,
1313 acquisition_counters: &WriterAcquisitionCounters,
1314 busy_timeout: Duration,
1315 mut set_busy_timeout: impl FnMut(&Connection, Duration) -> rusqlite::Result<()>,
1316) -> (rusqlite::Result<()>, Duration, u32) {
1317 let transaction_acquire_started = Instant::now();
1318 let mut begin_attempt = 1_u32;
1319 let mut retry_delays = WRITER_BEGIN_RETRY_DELAYS.into_iter();
1320 let mut busy_timeout_lowered = false;
1321 let begin_outcome = loop {
1322 match conn.execute_batch("BEGIN IMMEDIATE") {
1323 Ok(()) => break Ok(()),
1324 Err(error) if crate::timeout_sink::is_busy_or_locked(&error) => {
1325 // Every busy/locked refusal is counted here,
1326 // whether or not it goes on to be retried: this
1327 // is the pre-PR meaning of the counter, and the
1328 // outer match below no longer counts the final
1329 // refusal a second time.
1330 acquisition_counters.record_writer_task_begin_busy();
1331 let Some(delay) = retry_delays.next() else {
1332 break Err(error);
1333 };
1334 // The whole retry sequence shares one
1335 // `busy_timeout` budget: each SQLite attempt is
1336 // itself bounded by `busy_timeout`, so without a
1337 // shrinking budget three attempts could each
1338 // wait out a full window and multiply the
1339 // serialized writer's contention window instead
1340 // of bounding it.
1341 let remaining_budget =
1342 busy_timeout.saturating_sub(transaction_acquire_started.elapsed());
1343 if remaining_budget.is_zero() {
1344 break Err(error);
1345 }
1346 if let Err(set_err) = set_busy_timeout(conn, remaining_budget) {
1347 tracing::warn!(
1348 error = %set_err,
1349 "writer task: failed to lower busy_timeout for BEGIN \
1350 retry; surfacing the original busy refusal"
1351 );
1352 // A retry with the old timeout could exceed the shared budget.
1353 break Err(error);
1354 }
1355 busy_timeout_lowered = true;
1356 // Count only refusals that will actually be retried. A failed
1357 // timeout reduction leaves this refusal visible to the caller.
1358 acquisition_counters.record_writer_task_begin_busy_absorbed();
1359 tracing::debug!(
1360 attempt = begin_attempt,
1361 backoff_ms = delay.as_millis() as u64,
1362 budget_remaining_ms = remaining_budget.as_millis() as u64,
1363 "writer task: BEGIN IMMEDIATE refused busy; retrying before \
1364 request execution"
1365 );
1366 std::thread::sleep(delay);
1367 begin_attempt = begin_attempt.saturating_add(1);
1368 }
1369 Err(error) => break Err(error),
1370 }
1371 };
1372 let transaction_acquire = transaction_acquire_started.elapsed();
1373 // Restore the pool-configured busy_timeout only if a retry
1374 // actually lowered it, so the common uncontended request
1375 // never pays for an extra pragma write; the next request
1376 // dequeued on this same connection must still start from
1377 // the full configured budget.
1378 if busy_timeout_lowered {
1379 if let Err(restore_err) = set_busy_timeout(conn, busy_timeout) {
1380 tracing::warn!(
1381 error = %restore_err,
1382 "writer task: failed to restore busy_timeout after a BEGIN retry \
1383 sequence"
1384 );
1385 }
1386 }
1387 (begin_outcome, transaction_acquire, begin_attempt)
1388}
1389
1390struct BlockingWriterConnection {
1391 conn: Option<Connection>,
1392 admission: Arc<crate::pool::WriteAdmission>,
1393 volume_lease: Option<crate::disk_guard::VolumeLease>,
1394}
1395
1396impl BlockingWriterConnection {
1397 fn new(conn: Connection, admission: Arc<crate::pool::WriteAdmission>) -> Self {
1398 Self {
1399 conn: Some(conn),
1400 admission,
1401 volume_lease: None,
1402 }
1403 }
1404
1405 fn finish(
1406 mut self,
1407 state: Option<WriterTaskRequestState>,
1408 ) -> (Option<Connection>, Option<WriterTaskRequestState>) {
1409 if state.is_some() {
1410 self.retire();
1411 (None, state)
1412 } else {
1413 (self.conn.take(), None)
1414 }
1415 }
1416
1417 fn retire(&mut self) {
1418 if let Some(conn) = self.conn.take() {
1419 // A terminal failure has poisoned the admission; the request that
1420 // retired this writer already carries its terminal state.
1421 let _ = self.admission.close_retired_connection(conn);
1422 }
1423 }
1424}
1425
1426impl Drop for BlockingWriterConnection {
1427 fn drop(&mut self) {
1428 self.retire();
1429 }
1430}
1431
1432impl std::ops::Deref for BlockingWriterConnection {
1433 type Target = Connection;
1434
1435 fn deref(&self) -> &Connection {
1436 self.conn
1437 .as_ref()
1438 .expect("blocking writer owns its connection until settlement")
1439 }
1440}
1441
1442/// Drain loop: the sole caller of `BEGIN IMMEDIATE` for write traffic routed
1443/// through the channel. Busy/locked `BEGIN IMMEDIATE` refusals receive the
1444/// bounded retry above before a final failure replies the request's error via
1445/// [`AnyWriteRequest::reply_error`] without invoking the request's closure.
1446///
1447/// A request-operation panic is contained inside the concrete
1448/// [`WriteRequest<R>`] so its typed reply survives. A panic, failed rollback,
1449/// or otherwise poisoned connection makes the task terminal. The task then
1450/// closes admission, explicitly fails every already-queued request as
1451/// [`WriterTaskRequestState::NotStarted`], and exits permanently. There is no
1452/// supervisor or connection restart; later sends observe the closed channel.
1453/// See
1454/// `crates/khive-db/docs/api/writer-task.md` for the full failure matrix.
1455async fn run_writer_task(
1456 mut owner: (Connection, Option<crate::timeout_sink::WriterLease>),
1457 mut rx: mpsc::Receiver<Box<dyn AnyWriteRequest + Send>>,
1458 origin: khive_storage::tx_registry::TxOrigin,
1459 db: String,
1460 acquisition_counters: Arc<WriterAcquisitionCounters>,
1461 write_admission: Arc<crate::pool::WriteAdmission>,
1462 busy_timeout: Duration,
1463) {
1464 #[cfg(any(test, feature = "test-support"))]
1465 if let Err(error) = crate::test_hooks::adopt(&mut owner.0) {
1466 tracing::error!(%error, "writer task: test hook registration failed");
1467 }
1468 while let Some(mut request) = rx.recv().await {
1469 // The bounded-channel wait ends at this exact dequeue boundary.
1470 // Sampling inside the blocking closure would misattribute a saturated
1471 // Tokio blocking pool to writer-queue contention (#1849).
1472 let queue_wait = request.queue_wait();
1473 sealed::Sealed::start_execution(request.as_mut());
1474 let origin = origin.clone();
1475 let blocking_counters = Arc::clone(&acquisition_counters);
1476 let blocking_admission = Arc::clone(&write_admission);
1477 let blocking_db = db.clone();
1478 // Tuple field order drops the connection before its sink lease, both
1479 // while idle and when a cancelled parent discards a native result.
1480 let conn = owner.0;
1481 let blocking_sink_lease = owner.1.clone();
1482 let outcome = tokio::task::spawn_blocking(move || {
1483 // The issuer's lease class applies on this thread, so the lease
1484 // taken below is recorded as what the issuer's work is for.
1485 let _lease_class = request.lease_class().enter();
1486 let outcome = (|| {
1487 let mut conn = BlockingWriterConnection::new(conn, Arc::clone(&blocking_admission));
1488 let acquisition_counters = blocking_counters;
1489 // A top-level request deliberately skips BEGIN, so it would
1490 // silently join any transaction leaked by an earlier request.
1491 // Refuse every request before dispatch if the connection is not
1492 // demonstrably clean, then retire the writer task.
1493 if !conn.is_autocommit() {
1494 tracing::error!(
1495 "writer task: connection is not in autocommit mode before request dispatch; \
1496 retiring the poisoned writer without running the request"
1497 );
1498 let request_state = WriterTaskRequestState::NotStarted;
1499 request.reply_error(writer_task_terminated(request_state));
1500 return conn.finish(Some(request_state));
1501 }
1502
1503 // The lease precedes SQLite writer acquisition and remains held
1504 // until the request has committed, rolled back, or returned to
1505 // autocommit. Checkpoint requests deliberately skip both steps.
1506 conn.volume_lease = if request.is_checkpoint_bypass() {
1507 None
1508 } else {
1509 let class = if request.needs_vacuum_headroom() {
1510 crate::disk_guard::LeaseClass::Maintenance
1511 } else {
1512 crate::disk_guard::LeaseClass::WriterTask
1513 };
1514 match blocking_admission.acquire(class) {
1515 Ok(lease) => lease,
1516 Err(error) => {
1517 request.reply_error(error.into_storage_error(
1518 khive_storage::StorageCapability::Sql,
1519 "writer_task_admission",
1520 ));
1521 return conn.finish(None);
1522 }
1523 }
1524 };
1525
1526 let terminal_state = if request.is_top_level() {
1527 if !request.is_checkpoint_bypass() {
1528 let admission = if request.needs_vacuum_headroom() {
1529 blocking_admission.check_for_vacuum()
1530 } else {
1531 blocking_admission.check()
1532 };
1533 if let Err(error) = admission {
1534 request.reply_error(error.into_storage_error(
1535 khive_storage::StorageCapability::Sql,
1536 "writer_task_admission",
1537 ));
1538 return conn.finish(None);
1539 }
1540 }
1541 // ADR-067 Component A:
1542 // no BEGIN IMMEDIATE for this request — some statements
1543 // (e.g. VACUUM) are rejected by SQLite inside any open
1544 // transaction. Still runs on this task's dedicated
1545 // connection and still serialized one-request-at-a-time by
1546 // this same drain loop, so the single-writer guarantee
1547 // holds; only the transaction wrap is skipped.
1548 acquisition_counters.record_writer_task_acquisition();
1549 sealed::Sealed::execute_and_reply_top_level_reporting_terminal(
1550 request, &conn, queue_wait,
1551 )
1552 } else {
1553 let tx_span = khive_storage::tx_registry::register_scoped(
1554 Some("writer_task_tx".to_string()),
1555 origin,
1556 );
1557 let (begin_outcome, transaction_acquire, begin_attempt) =
1558 begin_immediate_with_retry(
1559 &conn,
1560 &acquisition_counters,
1561 busy_timeout,
1562 Connection::busy_timeout,
1563 );
1564 match begin_outcome {
1565 Ok(()) => {
1566 if let Err(error) = blocking_admission.check() {
1567 let request_state =
1568 match rollback_after_failure(&conn, "capacity admission") {
1569 RollbackDisposition::RolledBack => None,
1570 RollbackDisposition::SideEffectsUnknown => {
1571 Some(WriterTaskRequestState::SideEffectsUnknown)
1572 }
1573 };
1574 drop(tx_span);
1575 let error = if let Some(state) = request_state {
1576 writer_task_terminated(state)
1577 } else {
1578 error.into_storage_error(
1579 khive_storage::StorageCapability::Sql,
1580 "writer_task_admission",
1581 )
1582 };
1583 sealed::Sealed::reply_error_after_begin(
1584 request,
1585 error,
1586 queue_wait,
1587 transaction_acquire,
1588 );
1589 return conn.finish(request_state);
1590 }
1591 acquisition_counters.record_writer_task_acquisition();
1592 sealed::Sealed::execute_and_reply_reporting_terminal(
1593 request,
1594 &conn,
1595 Some(tx_span),
1596 queue_wait,
1597 transaction_acquire,
1598 )
1599 }
1600 Err(e) => {
1601 // Do NOT run the request's operation: `conn` never
1602 // entered a transaction, so executing the op's DML
1603 // here would run in autocommit mode and land partial
1604 // writes for a request the caller is about to be told
1605 // failed.
1606 crate::timeout_sink::maybe_emit_sqlite_full(&blocking_db, &e);
1607 tracing::warn!(
1608 error = %e,
1609 attempts = begin_attempt,
1610 "writer task: BEGIN IMMEDIATE failed; replying an \
1611 error without running the request's operation"
1612 );
1613 // Although BEGIN never opened a SQL transaction, the
1614 // scoped attempt is observable in tx_registry. Drop
1615 // it before waking the caller for the same reply-side
1616 // lifecycle guarantee as successful requests (#1790).
1617 drop(tx_span);
1618 // A busy/locked refusal was already counted inside
1619 // the retry loop above, including this final one —
1620 // classifying and counting it again here would
1621 // double it. Only a non-busy BEGIN failure (which
1622 // never enters the retry loop's busy arm) still
1623 // needs its counter recorded at this seam.
1624 let begin_error = writer_task_begin_error(e, busy_timeout);
1625 if !matches!(
1626 begin_error.without_sqlite_write_stage(),
1627 StorageError::WriterTaskBusy { .. }
1628 ) {
1629 acquisition_counters.record_writer_task_begin_error();
1630 }
1631 sealed::Sealed::reply_error_after_begin(
1632 request,
1633 begin_error,
1634 queue_wait,
1635 transaction_acquire,
1636 );
1637 None
1638 }
1639 }
1640 };
1641 conn.finish(terminal_state)
1642 })();
1643 (outcome, blocking_sink_lease)
1644 })
1645 .await;
1646
1647 match outcome {
1648 Ok(((Some(returned_conn), None), _sink_lease)) => owner.0 = returned_conn,
1649 Ok(((_returned_conn, Some(request_state)), _sink_lease)) => {
1650 acquisition_counters.record_writer_task_request_failure();
1651 if request_state == WriterTaskRequestState::SideEffectsUnknown {
1652 acquisition_counters.record_writer_task_side_effects_unknown();
1653 }
1654 tracing::error!(
1655 request_state = %request_state,
1656 "writer task reached a terminal request or connection state; closing and \
1657 failing the queue without restarting"
1658 );
1659 crate::timeout_sink::emit_writer_task_retirement(
1660 &db,
1661 &format!("terminal request state: {request_state}"),
1662 );
1663 close_and_fail_queued_requests(&mut rx).await;
1664 return;
1665 }
1666 Ok(((None, None), _sink_lease)) => {
1667 unreachable!("a reusable writer returns its connection")
1668 }
1669 Err(join_err) => {
1670 acquisition_counters.record_writer_task_request_failure();
1671 tracing::error!(
1672 error = %join_err,
1673 "writer task blocking closure failed outside the request \
1674 panic boundary; closing and failing the queue without restarting"
1675 );
1676 crate::timeout_sink::emit_writer_task_retirement(
1677 &db,
1678 &format!("blocking closure join failure: {join_err}"),
1679 );
1680 close_and_fail_queued_requests(&mut rx).await;
1681 return;
1682 }
1683 }
1684 }
1685}
1686
1687#[cfg(test)]
1688#[path = "writer_task_tests.rs"]
1689mod tests;
1690
1691#[cfg(test)]
1692#[path = "writer_task_lease_close_tests.rs"]
1693mod volume_lease_close_tests;
1694
1695#[cfg(test)]
1696#[path = "writer_task_slow_write_label_tests.rs"]
1697mod slow_write_label_tests;
1698
1699#[cfg(all(test, any(unix, windows)))]
1700#[path = "writer_task_identity_tests.rs"]
1701mod identity_tests;