Skip to main content

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 mut 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(guard.conn_mut());
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(guard.conn_mut());
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(guard.conn_mut());
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}