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