khive_db/sql_bridge/inline_bridge.rs
1use super::{
2 acquire_handle_slot, async_trait, bind_params, execute_prepared_batch, execute_query,
3 execute_query_page, execute_query_row, map_rusqlite_err, map_write_boundary_err, map_write_err,
4 open_standalone_writer_on_blocking, prepare_batch_statements, prepare_cached_sql_statement,
5 reject_transaction_control_statements, run_manual_atomic_unit, Any, Arc, AtomicEventRows,
6 AtomicUnitOp, ConnectionPool, PageRequest, PoolBackedReader, PoolBackedWriter,
7 SlotTimeoutClass, SqlRow, SqlStatement, SqlValue, SqliteError, SqliteReader, SqliteWriter,
8 StorageCapability, StorageError,
9};
10
11// =============================================================================
12// atomic_unit (ADR-067 Component A, Fork C slice 2)
13// =============================================================================
14
15/// A purely-synchronous `SqlReader`/`SqlWriter` over a borrowed connection,
16/// used to drive an [`AtomicUnitOp`] on the queued or in-memory path, where the
17/// closure body runs inside a `spawn_blocking` (synchronous
18/// `FnOnce(&rusqlite::Connection) -> ...`) rather than a real async context.
19///
20/// Every method here does plain, non-suspending rusqlite work — there is no
21/// real `.await` point anywhere in this impl — so [`block_on_sync`] driving
22/// the resulting future to completion with a single poll is sound, not a
23/// hack: the future can never actually be `Pending`.
24///
25/// `SqlReader`/`SqlWriter` both carry a `'static` supertrait bound (they are
26/// used as `Box<dyn ...>` elsewhere in this module), so this type cannot
27/// hold a real `&'c Connection` borrow — it would tie `InlineWriter` to a
28/// non-`'static` lifetime and, independently, `&Connection` is not `Send`
29/// (`Connection` is `!Sync`), which the `#[async_trait]`-generated futures
30/// require. A raw pointer sidesteps both: `*const Connection` is `Send` and
31/// `'static` on its face, and the safety burden (the pointee outliving
32/// every dereference) is upheld by each atomic-unit owner: it builds an
33/// `InlineWriter` from `conn: &Connection`, drives `op` to completion via
34/// `block_on_sync` synchronously, and drops the `InlineWriter` before that
35/// borrow ends, all within one stack frame.
36pub(super) struct InlineWriter {
37 pub(super) event_rows: Option<Arc<AtomicEventRows>>,
38 pub(super) conn: *const rusqlite::Connection,
39 pub(super) standalone_db: Option<String>,
40}
41
42// SAFETY: `InlineWriter` is never actually shared across a real thread
43// boundary — it is constructed, driven to completion synchronously via
44// `block_on_sync`, and dropped within a single call frame inside the
45// `spawn_blocking` closure (see `atomic_unit`). The `Send`
46// bound `async_trait` imposes on the futures below is a static
47// over-approximation for this restricted, single-threaded usage pattern.
48unsafe impl Send for InlineWriter {}
49
50impl InlineWriter {
51 /// SAFETY: valid for the lifetime of the enclosing synchronous scope in
52 /// `atomic_unit` (see the struct doc comment above) — the pointee is
53 /// never dereferenced after that scope ends.
54 fn conn(&self) -> &rusqlite::Connection {
55 unsafe { &*self.conn }
56 }
57
58 fn operation(&self, standalone: &'static str, inline: &'static str) -> &'static str {
59 if self.standalone_db.is_some() {
60 standalone
61 } else {
62 inline
63 }
64 }
65
66 fn map_write_error(&self, error: rusqlite::Error, operation: &'static str) -> StorageError {
67 if let Some(db) = &self.standalone_db {
68 crate::timeout_sink::maybe_emit_busy(
69 db,
70 crate::timeout_sink::Site::StandaloneSqlBridge,
71 &error,
72 );
73 }
74 map_write_err(error, operation)
75 }
76}
77
78#[async_trait]
79impl khive_storage::SqlReader for InlineWriter {
80 async fn query_row(
81 &mut self,
82 statement: SqlStatement,
83 ) -> khive_storage::types::StorageResult<Option<SqlRow>> {
84 execute_query_row(self.conn(), &statement).map_err(|error| {
85 map_rusqlite_err(
86 error,
87 self.operation("writer.query_row", "inline.query_row"),
88 )
89 })
90 }
91
92 async fn query_all(
93 &mut self,
94 statement: SqlStatement,
95 ) -> khive_storage::types::StorageResult<Vec<SqlRow>> {
96 execute_query(self.conn(), &statement).map_err(|error| {
97 map_rusqlite_err(
98 error,
99 self.operation("writer.query_all", "inline.query_all"),
100 )
101 })
102 }
103
104 async fn query_page(
105 &mut self,
106 statement: SqlStatement,
107 page: PageRequest,
108 ) -> khive_storage::types::StorageResult<Vec<SqlRow>> {
109 execute_query_page(self.conn(), &statement, &page).map_err(|error| {
110 map_rusqlite_err(
111 error,
112 self.operation("writer.query_page", "inline.query_page"),
113 )
114 })
115 }
116
117 async fn query_scalar(
118 &mut self,
119 statement: SqlStatement,
120 ) -> khive_storage::types::StorageResult<Option<SqlValue>> {
121 let row = khive_storage::SqlReader::query_row(self, statement).await?;
122 Ok(row.and_then(|r| r.columns.into_iter().next().map(|c| c.value)))
123 }
124
125 async fn explain(
126 &mut self,
127 statement: SqlStatement,
128 ) -> khive_storage::types::StorageResult<Vec<SqlRow>> {
129 let explain_stmt = SqlStatement {
130 sql: format!("EXPLAIN QUERY PLAN {}", statement.sql),
131 params: statement.params,
132 label: statement.label,
133 };
134 khive_storage::SqlReader::query_all(self, explain_stmt).await
135 }
136}
137
138#[async_trait]
139impl khive_storage::SqlWriter for InlineWriter {
140 async fn execute(
141 &mut self,
142 statement: SqlStatement,
143 ) -> khive_storage::types::StorageResult<u64> {
144 // Boundary: `execute_batch` owns transaction-control rejection;
145 // `atomic_unit` uses this one-statement primitive for its own boundary.
146 let operation = self.operation("execute", "inline.execute");
147 let mut stmt = prepare_cached_sql_statement(self.conn(), &statement.sql)
148 .map_err(|error| self.map_write_error(error, operation))?;
149 bind_params(&mut stmt, &statement.params)
150 .map_err(|error| self.map_write_error(error, operation))?;
151 let affected = stmt
152 .raw_execute()
153 .map_err(|error| self.map_write_error(error, operation))?;
154 if let Some(event_rows) = self.event_rows.as_deref() {
155 event_rows.observe(&statement, affected as u64);
156 }
157 Ok(affected as u64)
158 }
159
160 async fn execute_batch(
161 &mut self,
162 statements: Vec<SqlStatement>,
163 ) -> khive_storage::types::StorageResult<u64> {
164 // Runs inside the writer task's per-request `BEGIN IMMEDIATE`
165 // (atomic_unit flag-on path), so a caller `COMMIT` would close the
166 // task's transaction — reject transaction-control statements up
167 // front, same contract as every other `execute_batch`.
168 let operation = self.operation("execute_batch", "inline.execute_batch");
169 reject_transaction_control_statements(&statements, operation)?;
170 let prepared = prepare_batch_statements(self.conn(), &statements)
171 .map_err(|error| self.map_write_error(error, operation))?;
172 execute_prepared_batch(
173 self.conn(),
174 prepared,
175 &statements,
176 self.event_rows.as_deref(),
177 )
178 .map_err(|error| self.map_write_error(error, operation))
179 }
180
181 async fn execute_script(&mut self, script: String) -> khive_storage::types::StorageResult<()> {
182 // Boundary: this raw script path is internal maintenance only and is
183 // outside the `execute_batch` transaction-control contract.
184 self.conn().execute_batch(&script).map_err(|error| {
185 self.map_write_error(
186 error,
187 self.operation("execute_script", "inline.execute_script"),
188 )
189 })
190 }
191}
192
193/// Poll `fut` exactly once with a no-op waker and return its output.
194///
195/// Only sound for futures that never actually suspend — every caller in
196/// this module drives an [`InlineWriter`], whose methods are pure
197/// synchronous rusqlite calls with no real `.await` point.
198///
199/// ADR-067 Component A: this used to
200/// `unreachable!()`-panic on `Poll::Pending`, and a panicking closure
201/// running inside the writer task's `spawn_blocking` (see
202/// `SqlBridge::atomic_unit`'s flag-on branch) would surface as a
203/// `JoinError` in `run_writer_task`, which is treated as fatal — the writer
204/// task exits and every subsequent `WriterTaskHandle::send` on this pool
205/// fails for the rest of the process. A future `atomic_unit` caller whose
206/// closure ever gains a real suspend point (this file's own contract
207/// already forbids it, but the invariant is enforced by convention, not the
208/// type system) would take down the writer task for the whole daemon.
209/// Returning `Err` instead lets `Pending` flow through the SAME error path
210/// as any other `atomic_unit` op failure: `WriteRequest::execute_and_reply`
211/// treats it as an ordinary `Err`, issues `ROLLBACK` on the writer task's
212/// held transaction, replies the error to the caller, and the writer task's
213/// `spawn_blocking` closure returns normally (not via panic) — so the task
214/// keeps draining subsequent requests instead of dying with the whole pool.
215pub(super) fn block_on_sync<F: std::future::Future>(fut: F) -> Result<F::Output, StorageError> {
216 use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
217
218 fn no_op(_: *const ()) {}
219 fn clone_waker(_: *const ()) -> RawWaker {
220 RawWaker::new(std::ptr::null(), &VTABLE)
221 }
222 static VTABLE: RawWakerVTable = RawWakerVTable::new(clone_waker, no_op, no_op, no_op);
223
224 // SAFETY: every `RawWakerVTable` function is a no-op that never
225 // dereferences the data pointer, so a null data pointer is sound.
226 let raw_waker = RawWaker::new(std::ptr::null(), &VTABLE);
227 let waker = unsafe { Waker::from_raw(raw_waker) };
228 let mut cx = Context::from_waker(&waker);
229
230 let mut fut = std::pin::pin!(fut);
231 match fut.as_mut().poll(&mut cx) {
232 Poll::Ready(v) => Ok(v),
233 Poll::Pending => {
234 tracing::error!(target: "khive_db::sql_bridge",
235 "block_on_sync: atomic_unit future suspended on its first poll — \
236 the closure passed to SqlAccess::atomic_unit must be non-blocking \
237 (synchronous InlineWriter calls only, no real .await point)"
238 );
239 Err(StorageError::Internal(
240 "atomic_unit future suspended — closure must be non-blocking".to_string(),
241 ))
242 }
243 }
244}
245
246// =============================================================================
247// SqlBridge: the SqlAccess implementor
248// =============================================================================
249
250/// Bridges `ConnectionPool` to `khive_storage::SqlAccess`.
251///
252/// Dispatches based on whether the pool is file-backed or in-memory:
253/// - File-backed: pooled ordinary reader operations and a lazy standalone
254/// connection only for explicitly admitted multi-call read transactions,
255/// plus standalone writer connections capped at one live handle; atomic
256/// units drive a single registered raw transaction span.
257/// - In-memory: pool-backed connections per query (single shared connection).
258pub struct SqlBridge {
259 pool: Arc<ConnectionPool>,
260 pub(super) is_file_backed: bool,
261}
262
263impl SqlBridge {
264 /// Create a new bridge wrapping the given pool.
265 pub fn new(pool: Arc<ConnectionPool>, _is_file_backed: bool) -> Self {
266 // The legacy hint is not an authority for choosing an unguarded
267 // in-memory writer. A caller cannot route a file-backed pool through
268 // PoolBackedWriter by supplying `false`.
269 let is_file_backed = pool.canonical_path().is_some();
270 Self {
271 pool,
272 is_file_backed,
273 }
274 }
275}
276
277#[async_trait]
278impl khive_storage::SqlAccess for SqlBridge {
279 fn database_path(&self) -> Option<std::path::PathBuf> {
280 self.pool.canonical_path().map(std::path::Path::to_path_buf)
281 }
282
283 async fn reader(
284 &self,
285 ) -> khive_storage::types::StorageResult<Box<dyn khive_storage::SqlReader>> {
286 if self.is_file_backed {
287 Ok(Box::new(SqliteReader {
288 handle: None,
289 pool: Arc::clone(&self.pool),
290 poisoned: false,
291 }))
292 } else {
293 Ok(Box::new(PoolBackedReader {
294 pool: Arc::clone(&self.pool),
295 transaction: None,
296 }))
297 }
298 }
299
300 async fn writer(
301 &self,
302 ) -> khive_storage::types::StorageResult<Box<dyn khive_storage::SqlWriter>> {
303 if self.is_file_backed {
304 if self.pool.config().read_only {
305 return Err(StorageError::Pool {
306 operation: "writer".into(),
307 message: "backend is read-only".into(),
308 });
309 }
310 let db = crate::timeout_sink::db_label(&self.pool);
311 // ADR-136 D1 gate 1: queue-first. The handle lookup runs BEFORE
312 // any standalone connection is opened, and a lookup failure is
313 // propagated (never silently degraded) when strict routing is
314 // on. Only the flag-off/degraded case still opens a standalone
315 // connection.
316 let writer_task = match self.pool.writer_task_handle() {
317 Ok(handle) => handle,
318 Err(e) => {
319 if self.pool.config().write_routing_strict {
320 return Err(e);
321 }
322 tracing::warn!(target: "khive_db::sql_bridge",
323 error = %e,
324 "KHIVE_WRITE_ROUTING is not strict; writer() degrades to the \
325 standalone-connection path"
326 );
327 None
328 }
329 };
330 if writer_task.is_none() && self.pool.config().write_routing_strict {
331 return Err(StorageError::Pool {
332 operation: "writer".into(),
333 message: "KHIVE_WRITE_ROUTING=strict but no writer-task handle is \
334 available; refusing to fall back to a direct connection"
335 .into(),
336 });
337 }
338 if writer_task.is_none() && self.pool.write_queue_active() {
339 // The queue is enabled but this call didn't get a handle
340 // (spawn/runtime degrade) — a direct-route violation in the
341 // making once this writer's execute*/query* methods run.
342 // In-memory pools are excluded: they never spawn a writer
343 // task by documented design (explicit `Some(true)` degrades),
344 // so a violation row there would be noise, not signal.
345 crate::timeout_sink::emit_direct_route_violation(
346 &db,
347 crate::timeout_sink::Site::DirectRouteSqlBridgeWriter,
348 );
349 }
350 // A standalone read-write connection is opened only when there is
351 // no queue handle to route writes through — `SqliteWriter`'s
352 // `SqlReader` methods (`query_row`/`query_all`/`query_page`)
353 // use pooled readers in the queue-backed case and lazily open the
354 // closed standalone exception only for an explicit deferred read
355 // transaction. Production callers do read through a `writer()`
356 // handle, so both routes are live.
357 // The standalone open acquires the pool-wide one-permit writer
358 // budget first, and the permit travels in the handle for the
359 // handle's whole lifetime — a queue-backed handle holds no
360 // writer permit (its writes route through the writer task), so
361 // this budget caps exactly the standalone read-write
362 // connections.
363 if writer_task.is_none() {
364 let handle_slot = acquire_handle_slot(
365 self.pool.sql_bridge_writer_slots(),
366 self.pool.config().checkout_timeout,
367 "sql_bridge.writer_handle",
368 SlotTimeoutClass::Admission,
369 )
370 .await?;
371 return open_standalone_writer_on_blocking(Arc::clone(&self.pool), handle_slot)
372 .await;
373 }
374 Ok(Box::new(SqliteWriter {
375 observe_direct_errors: true,
376 event_rows: None,
377 handle: None,
378 writer_task,
379 origin: self.pool.origin(),
380 db,
381 pool: Arc::clone(&self.pool),
382 }))
383 } else {
384 Ok(Box::new(PoolBackedWriter {
385 pool: Arc::clone(&self.pool),
386 }))
387 }
388 }
389
390 /// Implements the trait's atomic-unit suspend-free invariant
391 /// (`SqlAccess::atomic_unit`'s doc comment): on the queued and in-memory branches,
392 /// `op` is driven through `block_on_sync` on an `InlineWriter` — a
393 /// single-poll driver that returns `Err` the instant `op`'s future is
394 /// `Pending` instead of ever actually suspending. `op` must therefore
395 /// issue only synchronous DML; see `InlineWriter`'s and
396 /// `block_on_sync`'s doc comments for the full mechanics and why this
397 /// restriction is load-bearing (a suspended poll inside the writer
398 /// task's `spawn_blocking` would otherwise block that task on external
399 /// async work while holding the single write connection).
400 async fn atomic_unit(
401 &self,
402 op: AtomicUnitOp,
403 ) -> khive_storage::types::StorageResult<Box<dyn Any + Send>> {
404 let event_rows = Arc::new(AtomicEventRows::default());
405 let result = async {
406 if self.is_file_backed {
407 if self.pool.config().read_only {
408 return Err(StorageError::Pool {
409 operation: "atomic_unit".into(),
410 message: "backend is read-only".into(),
411 });
412 }
413 // Best-effort, same guard `writer()` uses: `Ok(None)` on flag-off;
414 // `Err(WriterTaskNoRuntime)` propagates loud rather than silently
415 // falling back to a competing connection from a sync caller. ADR-136
416 // D1 gate 3: `Ok(None)` under strict routing is ALSO a fail-closed
417 // error (queue was requested but unavailable), not just a degrade.
418 let handle = self.pool.writer_task_handle()?;
419 if handle.is_none() && self.pool.config().write_routing_strict {
420 return Err(StorageError::Pool {
421 operation: "atomic_unit".into(),
422 message: "KHIVE_WRITE_ROUTING=strict but no writer-task handle is \
423 available; refusing to fall back to a direct connection"
424 .into(),
425 });
426 }
427 if handle.is_none() && self.pool.write_queue_active() {
428 crate::timeout_sink::emit_direct_route_violation(
429 &crate::timeout_sink::db_label(&self.pool),
430 crate::timeout_sink::Site::DirectRouteAtomicUnit,
431 );
432 }
433 if let Some(writer_task) = handle {
434 // Flag-on: ONE queued WriteRequest. `run_writer_task` already
435 // has an open `BEGIN IMMEDIATE` on its dedicated connection
436 // before this closure runs and issues `COMMIT`/`ROLLBACK`
437 // after it returns — `op` must not (and, via `InlineWriter`,
438 // does not) issue its own transaction control.
439 let pending_event_rows = Arc::clone(&event_rows);
440 return writer_task
441 .send_bounded_at(
442 move |conn| {
443 let mut inline = InlineWriter {
444 event_rows: Some(Arc::clone(&pending_event_rows)),
445 conn: conn as *const rusqlite::Connection,
446 standalone_db: None,
447 };
448 // Flatten: `block_on_sync` now returns `Result<F::Output,
449 // StorageError>` (outer = "did the future actually
450 // resolve on first poll", inner = the op's own
451 // `StorageResult`) instead of panicking on `Pending`
452 // (ADR-067 Component A). Either
453 // error flows through this closure's ordinary `Err`
454 // return, which `WriteRequest::execute_and_reply`
455 // already turns into a normal ROLLBACK + error reply —
456 // no panic, so the writer task survives.
457 match block_on_sync(op(&mut inline)) {
458 Ok(inner) => inner,
459 Err(e) => Err(e),
460 }
461 },
462 "atomic_unit",
463 )
464 .await;
465 }
466 // Contract: this acquire waits on the pool-wide one-permit
467 // writer-handle budget — the same permit a live `writer()` handle
468 // holds for its lifetime — so it times out with
469 // `StorageError::AdmissionTimeout` after `checkout_timeout` while a writer
470 // handle is checked out (and a `writer()` call times out while
471 // this unit runs). Callers must not hold a boxed writer handle
472 // across an `atomic_unit()` call on the same pool; drop the
473 // handle first. The `writer_task` branch above never touches this
474 // budget.
475 let handle_slot = acquire_handle_slot(
476 self.pool.sql_bridge_writer_slots(),
477 self.pool.config().checkout_timeout,
478 "sql_bridge.atomic_unit_handle",
479 SlotTimeoutClass::Admission,
480 )
481 .await?;
482 run_manual_atomic_unit(
483 Arc::clone(&self.pool),
484 handle_slot,
485 op,
486 Arc::clone(&event_rows),
487 )
488 .await
489 .inspect_err(|error| self.pool.record_direct_writer_error(error))
490 } else {
491 // Every statement shares one connection. Keep its guard through
492 // commit/rollback so other units and ordinary writes cannot join it.
493 let pool = Arc::clone(&self.pool);
494 let pending_event_rows = Arc::clone(&event_rows);
495 tokio::task::spawn_blocking(move || {
496 let guard = pool.try_writer().map_err(|error: SqliteError| {
497 StorageError::driver(StorageCapability::Sql, "atomic_unit", error)
498 })?;
499 let conn = guard.conn();
500 if !conn.is_autocommit() {
501 pool.retire_pooled_writer(conn);
502 return Err(StorageError::writer_task_terminated(
503 khive_storage::WriterTaskRequestState::SideEffectsUnknown,
504 ));
505 }
506 if let Err(error) = conn.execute_batch("BEGIN IMMEDIATE") {
507 if !conn.is_autocommit() {
508 pool.retire_pooled_writer(conn);
509 return Err(SqliteError::settlement_with_cause(
510 &error,
511 khive_storage::error::SqliteWriteStage::Begin,
512 )
513 .into_storage_error(StorageCapability::Sql, "atomic_unit.begin"));
514 }
515 return Err(map_write_boundary_err(
516 error,
517 "atomic_unit.begin",
518 khive_storage::error::SqliteWriteStage::Begin,
519 ))
520 .inspect_err(|error| pool.record_direct_writer_error(error));
521 }
522 let _tx_handle = khive_storage::tx_registry::register_scoped(
523 Some("atomic_unit".to_string()),
524 pool.origin(),
525 );
526 let (result, terminal_state) = crate::writer_task::execute_wrapped_transaction(
527 conn,
528 "atomic_unit.commit",
529 |conn| {
530 let mut inline = InlineWriter {
531 event_rows: Some(Arc::clone(&pending_event_rows)),
532 conn: conn as *const rusqlite::Connection,
533 standalone_db: None,
534 };
535 block_on_sync(op(&mut inline)).and_then(|result| result)
536 },
537 );
538 if terminal_state.is_some() {
539 pool.retire_pooled_writer(conn);
540 }
541 result.inspect_err(|error| pool.record_direct_writer_error(error))
542 })
543 .await
544 .map_err(|error| {
545 StorageError::driver(StorageCapability::Sql, "atomic_unit", error)
546 })?
547 }
548 }
549 .await;
550 khive_storage::usage::account_event_write(
551 result.as_ref().map(|_| event_rows.committed_rows()),
552 );
553 result
554 }
555}