Skip to main content

uqa_storage_sqlite/connection/
logical.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Connection clones and store handles share one logical transaction context.
8
9use uqa_storage::mvcc::{DatabaseId, VersionError, VersionedSessionOptions};
10use uqa_storage::read_control::StorageReadControl;
11use uqa_storage::StorageBackendResult;
12
13use super::{
14    Arc, Connection, KeyValueStore, ManagedConnection, Result, SQLiteError, SessionState,
15    VersionedKeyValueStore,
16};
17
18pub(super) struct BoundRecordSession {
19    pub(super) store: Arc<VersionedKeyValueStore>,
20    /// Stable native data namespace, separate from the store's transaction history identity.
21    pub(super) native: Option<DatabaseId>,
22}
23
24impl std::ops::Deref for BoundRecordSession {
25    type Target = VersionedKeyValueStore;
26
27    fn deref(&self) -> &Self::Target {
28        &self.store
29    }
30}
31
32impl BoundRecordSession {
33    pub(super) fn new_session_with_cancellation(
34        &self,
35        cancellation: &uqa_core::CancellationToken,
36    ) -> Self {
37        Self {
38            store: Arc::new(self.store.new_session_with_cancellation(cancellation)),
39            native: self.native,
40        }
41    }
42}
43
44impl ManagedConnection {
45    pub(crate) fn require_sequence_value_durability(&self) -> Result<()> {
46        self.surface_cleanup_failure()?;
47        let _gate = self.session.gate.read();
48        if let Some(logical) = self.session.logical.get() {
49            logical.require_sequence_value_durability()?;
50        }
51        Ok(())
52    }
53
54    pub(crate) fn new_sequence_value_session(
55        &self,
56        cancellation: &uqa_core::CancellationToken,
57    ) -> Result<Self> {
58        cancellation.check()?;
59        let _gate = self.session.gate.read();
60        let session = SessionState::with_cancellation(cancellation.clone());
61        if let Some(logical) = self.session.logical.get() {
62            let _ = session.logical.set(Arc::new(BoundRecordSession {
63                store: Arc::new(logical.new_sequence_value_session(cancellation)),
64                native: logical.native,
65            }));
66        }
67        Ok(Self {
68            pool: Arc::clone(&self.pool),
69            session: Arc::new(session),
70            record_access: self.record_access,
71        })
72    }
73
74    pub(crate) fn completed_commit(&self) -> Option<uqa_storage::mvcc::CommitReceipt> {
75        // An optional cache hint must not consume the next operation's cleanup diagnostic.
76        if self.session.cleanup_failure.lock().is_some() {
77            return None;
78        }
79        let _gate = self.session.gate.read();
80        self.session.logical.get()?.completed_commit()
81    }
82
83    pub(crate) fn committed_data_revision(&self) -> Option<uqa_storage::CommittedDataRevision> {
84        if self.session.cleanup_failure.lock().is_some() {
85            return None;
86        }
87        let _gate = self.session.gate.read();
88        self.session
89            .logical
90            .get()
91            .and_then(|logical| logical.committed_data_revision())
92    }
93
94    pub(crate) fn snapshot_registry(
95        &self,
96        identity: DatabaseId,
97    ) -> uqa_storage::mvcc::VersionResult<Arc<uqa_storage::mvcc::SnapshotRegistry>> {
98        let mut retained = self.pool.snapshot_registry.lock();
99        if let Some((old_identity, registry)) = retained.as_ref() {
100            if let Some(registry) = registry.upgrade() {
101                if *old_identity != identity {
102                    return Err(VersionError::WrongDatabase);
103                }
104                return Ok(registry);
105            }
106        }
107        let registry = Arc::new(uqa_storage::mvcc::SnapshotRegistry::default());
108        *retained = Some((identity, Arc::downgrade(&registry)));
109        Ok(registry)
110    }
111
112    /// Create an independent logical session over the same database pool.
113    /// Explicit transactions started on either session are isolated and never
114    /// capture operations issued through the other session.
115    #[must_use]
116    pub fn new_session(&self) -> Self {
117        self.new_session_with_cancellation(&uqa_core::CancellationToken::new())
118    }
119
120    /// Use a fresh transaction context while sharing the invoking execution's write cancellation. Existing sessions and clones keep their original token.
121    #[must_use]
122    pub fn new_session_with_cancellation(
123        &self,
124        cancellation: &uqa_core::CancellationToken,
125    ) -> Self {
126        let _gate = self.session.gate.read();
127        let session = SessionState::with_cancellation(cancellation.clone());
128        if let Some(logical) = self.session.logical.get() {
129            let _ = session.logical.set(Arc::new(
130                logical.new_session_with_cancellation(cancellation),
131            ));
132        }
133        Self {
134            pool: Arc::clone(&self.pool),
135            session: Arc::new(session),
136            record_access: self.record_access,
137        }
138    }
139
140    /// Admit a versioned maintenance writer to the original operation's allowance without changing any existing session's transaction or cancellation.
141    pub(crate) fn new_controlled_session(
142        &self,
143        control: &StorageReadControl,
144    ) -> StorageBackendResult<Self> {
145        control.check()?;
146        let _gate = self.session.gate.read();
147        let logical = self.session.logical.get().ok_or_else(|| {
148            uqa_storage::StorageBackendError::Other(
149                "controlled sessions require bound versioned records".into(),
150            )
151        })?;
152        let session = SessionState::with_cancellation(control.cancellation().clone());
153        let _ = session.logical.set(Arc::new(BoundRecordSession {
154            store: Arc::new(logical.store.new_controlled_session(control)),
155            native: logical.native,
156        }));
157        Ok(Self {
158            pool: Arc::clone(&self.pool),
159            session: Arc::new(session),
160            record_access: self.record_access,
161        })
162    }
163
164    /// Keep the bound record view and its logical reader attribution in an independent read-only connection. The source session retains ownership of publication and transaction completion.
165    pub(crate) fn new_retained_read_session(
166        &self,
167        cancellation: &uqa_core::CancellationToken,
168    ) -> Result<Self> {
169        self.new_record_read_session(cancellation, |store| {
170            store.new_retained_read_session(cancellation)
171        })
172    }
173
174    pub(crate) fn capture_committed_read_boundary(
175        &self,
176    ) -> StorageBackendResult<Arc<uqa_storage::mvcc::CommittedReadBoundary>> {
177        self.surface_cleanup_failure()?;
178        let _gate = self.session.gate.read();
179        let logical = self
180            .session
181            .logical
182            .get()
183            .ok_or(SQLiteError::LogicalSessionRequired)?;
184        logical.capture_committed_read_boundary()
185    }
186
187    pub(crate) fn new_read_session_with_private_changes(
188        &self,
189        boundary: &uqa_storage::mvcc::CommittedReadBoundary,
190        cancellation: &uqa_core::CancellationToken,
191    ) -> Result<Self> {
192        self.new_record_read_session(cancellation, |store| {
193            store.new_read_session_with_private_changes(boundary, cancellation)
194        })
195    }
196
197    fn new_record_read_session(
198        &self,
199        cancellation: &uqa_core::CancellationToken,
200        retain: impl FnOnce(
201            &uqa_storage::mvcc::VersionedKeyValueStore,
202        ) -> StorageBackendResult<uqa_storage::mvcc::VersionedKeyValueStore>,
203    ) -> Result<Self> {
204        self.surface_cleanup_failure()?;
205        let _gate = self.session.gate.read();
206        let logical = self
207            .session
208            .logical
209            .get()
210            .ok_or(SQLiteError::LogicalSessionRequired)?;
211        let store = retain(&logical.store)?;
212        let session = SessionState::with_cancellation(cancellation.clone());
213        let _ = session.logical.set(Arc::new(BoundRecordSession {
214            store: Arc::new(store),
215            native: logical.native,
216        }));
217        Ok(Self {
218            pool: Arc::clone(&self.pool),
219            session: Arc::new(session),
220            record_access: self.record_access,
221        })
222    }
223
224    /// Share the token used for autonomous allocation and record publication. Cleanup reads and rollback remain independent of this flag.
225    pub fn write_cancellation(&self) -> uqa_core::CancellationToken {
226        self.session.write_cancellation.clone()
227    }
228
229    /// Transaction ownership selected for this connection and inherited by its independent sessions.
230    pub fn transaction_model(&self) -> uqa_storage::StorageTransactionModel {
231        let _gate = self.session.gate.read();
232        self.session.logical.get().map_or(
233            uqa_storage::StorageTransactionModel::ProviderSerialized,
234            |logical| logical.transaction_model(),
235        )
236    }
237
238    pub(crate) fn record_connection(&self) -> Self {
239        Self {
240            pool: Arc::clone(&self.pool),
241            session: Arc::new(SessionState::new()),
242            record_access: true,
243        }
244    }
245
246    /// Run a record read on a pooled connection, with the connection's memory of the committed state a store last validated. A record connection pins no transaction, so the connection serves this call alone.
247    pub(crate) fn with_record_read<R>(
248        &self,
249        operation: impl FnOnce(&Connection, &std::cell::Cell<Option<super::ValidatedRead>>) -> Result<R>,
250    ) -> Result<R> {
251        self.surface_cleanup_failure()?;
252        let _gate = self.session.gate.read();
253        if !self.record_access || self.session.transaction.lock().is_some() {
254            return Err(SQLiteError::SessionMappingMismatch);
255        }
256        let connection = self.pool.checkout()?;
257        let physical = connection.physical()?;
258        operation(&physical.connection, &physical.validated_read)
259    }
260
261    pub(crate) fn with_record_connection<R>(
262        &self,
263        control: &StorageReadControl,
264        operation: impl FnOnce(&Connection) -> Result<R>,
265    ) -> Result<R> {
266        self.surface_cleanup_failure()?;
267        let _gate = self.session.gate.read();
268        if !self.record_access || self.session.transaction.lock().is_some() {
269            return Err(SQLiteError::SessionMappingMismatch);
270        }
271        let connection = self
272            .pool
273            .checkout_with_cancellation(Some(control.cancellation()))?;
274        operation(connection.connection()?)
275    }
276
277    pub(crate) fn bind_records(
278        &self,
279        options: VersionedSessionOptions,
280    ) -> Result<Arc<VersionedKeyValueStore>> {
281        self.surface_cleanup_failure()?;
282        let _gate = self.session.gate.write();
283        if let Some(logical) = self.session.logical.get() {
284            if logical.native.is_some() {
285                return Err(SQLiteError::SessionMappingMismatch);
286            }
287            if logical.options().retained_bytes != options.retained_bytes {
288                return Err(SQLiteError::SessionOptionsMismatch);
289            }
290            return Ok(Arc::clone(&logical.store));
291        }
292        if self.session.transaction.lock().is_some() {
293            return Err(SQLiteError::TransactionAlreadyActive);
294        }
295        let identity = self.storage_identity()?;
296        let records = crate::SQLiteRecordStore::for_key_value(
297            self,
298            &StorageReadControl::with_limit(options.retained_bytes),
299        )
300        .map_err(VersionError::into_storage_error)?;
301        let logical = Arc::new(VersionedKeyValueStore::new_with_cancellation(
302            Arc::new(records),
303            identity,
304            options,
305            self.write_cancellation(),
306        ));
307        self.session
308            .logical
309            .set(Arc::new(BoundRecordSession {
310                store: Arc::clone(&logical),
311                native: None,
312            }))
313            .map_err(|_| SQLiteError::SessionOptionsMismatch)?;
314        Ok(logical)
315    }
316
317    pub(crate) fn with_records<R>(
318        &self,
319        operation: impl FnOnce(&VersionedKeyValueStore) -> StorageBackendResult<R>,
320    ) -> StorageBackendResult<R> {
321        self.surface_cleanup_failure()?;
322        let _gate = self.session.gate.read();
323        let logical = self
324            .session
325            .logical
326            .get()
327            .ok_or(SQLiteError::LogicalSessionRequired)?;
328        if logical.native.is_some() {
329            return Err(SQLiteError::SessionMappingMismatch.into());
330        }
331        operation(logical)
332    }
333
334    pub(crate) fn retention_control(
335        &self,
336    ) -> Option<uqa_storage::read_control::StorageReadControl> {
337        self.session
338            .logical
339            .get()
340            .map(|logical| logical.retention_control())
341    }
342
343    pub(crate) fn begin_record_read(&self) -> Result<()> {
344        self.surface_cleanup_failure()?;
345        let _gate = self.session.gate.write();
346        let logical = self
347            .session
348            .logical
349            .get()
350            .ok_or(SQLiteError::LogicalSessionRequired)?;
351        if logical.in_transaction() {
352            return Err(SQLiteError::TransactionAlreadyActive);
353        }
354        logical.begin_read_transaction().map_err(Into::into)
355    }
356
357    /// Advance a bound native or Key/Value command view through the common session, without opening a physical writer. Legacy physical transactions require their existing transaction boundary instead.
358    pub fn refresh_transaction_snapshot(
359        &self,
360        cancellation: &uqa_core::CancellationToken,
361    ) -> Result<()> {
362        self.surface_cleanup_failure()?;
363        let _gate = self.session.gate.write();
364        self.session
365            .logical
366            .get()
367            .ok_or(SQLiteError::LogicalSessionRequired)?
368            .refresh_transaction_snapshot(cancellation)
369            .map_err(Into::into)
370    }
371
372    pub(super) fn check_native_access(&self, connection: &Connection) -> Result<()> {
373        if self.record_access {
374            return Ok(());
375        }
376        let versioned: bool = connection.prepare_cached(
377            "SELECT EXISTS(SELECT 1 FROM sqlite_schema WHERE (name = '_key_value' AND type = 'view') OR name GLOB '_uqa_mvcc_native_*')",
378        )?.query_row([], |row| row.get(0))?;
379        if versioned {
380            return Err(SQLiteError::LogicalSessionRequired);
381        }
382        Ok(())
383    }
384
385    /// Access physical `SQLite` state for explicit diagnostics or maintenance outside any session transaction. This does not read private logical changes; ordinary stores must use their owning transaction interface. Record-table write guards remain active.
386    pub fn with_physical<R>(&self, operation: impl FnOnce(&Connection) -> Result<R>) -> Result<R> {
387        self.surface_cleanup_failure()?;
388        let _gate = self.session.gate.write();
389        if self.session.transaction.lock().is_some()
390            || self
391                .session
392                .logical
393                .get()
394                .is_some_and(|logical| logical.in_transaction())
395        {
396            return Err(SQLiteError::TransactionAlreadyActive);
397        }
398        let connection = self.pool.checkout()?;
399        operation(connection.connection()?)
400    }
401}
402
403#[cfg(test)]
404mod tests {
405    use super::*;
406    use uqa_storage::mvcc::{CommitErrorOutcome, CommitFailure, DatabaseId, StorageTransactionId};
407    use uqa_storage::StorageBackendError;
408
409    #[test]
410    fn record_checkout_cancellation_does_not_wait_for_a_retained_pool_connection() {
411        use std::{sync::mpsc, thread, time::Duration};
412
413        let connection = ManagedConnection::open_in_memory()
414            .unwrap()
415            .record_connection();
416        let held = connection.pool.checkout().unwrap();
417        let control = StorageReadControl::with_limit(1 << 20);
418        let cancellation = control.cancellation().clone();
419        let (started_tx, started_rx) = mpsc::channel();
420        let (finished_tx, finished_rx) = mpsc::channel();
421        thread::scope(|scope| {
422            let worker = scope.spawn(|| {
423                started_tx.send(()).unwrap();
424                let result = connection.with_record_connection(&control, |_| {
425                    panic!("cancelled checkout must not enter the operation")
426                });
427                finished_tx.send(result).unwrap();
428            });
429            started_rx.recv_timeout(Duration::from_secs(30)).unwrap();
430            cancellation.cancel();
431            let result = finished_rx.recv_timeout(Duration::from_secs(30));
432            drop(held);
433            worker.join().unwrap();
434            assert!(matches!(
435                result.unwrap(),
436                Err::<(), _>(SQLiteError::Cancelled(_))
437            ));
438        });
439    }
440
441    #[test]
442    fn storage_error_conversion_preserves_an_indeterminate_commit_identity() {
443        let transaction = StorageTransactionId::new(DatabaseId::from_bytes([7; 16]), 3).unwrap();
444        let original = StorageBackendError::backend(
445            "MVCC",
446            CommitFailure::Indeterminate {
447                transaction,
448                source: StorageBackendError::Other("commit reply lost".into()),
449            },
450        );
451        let converted = StorageBackendError::from(SQLiteError::from(original));
452        assert_eq!(
453            converted.commit_outcome(),
454            Some(CommitErrorOutcome::Indeterminate(transaction))
455        );
456        let StorageBackendError::Backend { backend, source } = converted else {
457            panic!("typed commit outcome was lost");
458        };
459        assert_eq!(backend, "MVCC");
460        assert!(
461            matches!(source.downcast_ref::<CommitFailure>(), Some(CommitFailure::Indeterminate { transaction: found, .. }) if *found == transaction)
462        );
463    }
464}