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.surface_cleanup_failure()?;
170        let _gate = self.session.gate.read();
171        let logical = self
172            .session
173            .logical
174            .get()
175            .ok_or(SQLiteError::LogicalSessionRequired)?;
176        let store = logical.new_retained_read_session(cancellation)?;
177        let session = SessionState::with_cancellation(cancellation.clone());
178        let _ = session.logical.set(Arc::new(BoundRecordSession {
179            store: Arc::new(store),
180            native: logical.native,
181        }));
182        Ok(Self {
183            pool: Arc::clone(&self.pool),
184            session: Arc::new(session),
185            record_access: self.record_access,
186        })
187    }
188
189    /// Share the token used for autonomous allocation and record publication. Cleanup reads and rollback remain independent of this flag.
190    pub fn write_cancellation(&self) -> uqa_core::CancellationToken {
191        self.session.write_cancellation.clone()
192    }
193
194    /// Transaction ownership selected for this connection and inherited by its independent sessions.
195    pub fn transaction_model(&self) -> uqa_storage::StorageTransactionModel {
196        let _gate = self.session.gate.read();
197        self.session.logical.get().map_or(
198            uqa_storage::StorageTransactionModel::ProviderSerialized,
199            |logical| logical.transaction_model(),
200        )
201    }
202
203    pub(crate) fn record_connection(&self) -> Self {
204        Self {
205            pool: Arc::clone(&self.pool),
206            session: Arc::new(SessionState::new()),
207            record_access: true,
208        }
209    }
210
211    /// 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.
212    pub(crate) fn with_record_read<R>(
213        &self,
214        operation: impl FnOnce(&Connection, &std::cell::Cell<Option<super::ValidatedRead>>) -> Result<R>,
215    ) -> Result<R> {
216        self.surface_cleanup_failure()?;
217        let _gate = self.session.gate.read();
218        if !self.record_access || self.session.transaction.lock().is_some() {
219            return Err(SQLiteError::SessionMappingMismatch);
220        }
221        let connection = self.pool.checkout()?;
222        let physical = connection.physical()?;
223        operation(&physical.connection, &physical.validated_read)
224    }
225
226    pub(crate) fn with_record_connection<R>(
227        &self,
228        control: &StorageReadControl,
229        operation: impl FnOnce(&Connection) -> Result<R>,
230    ) -> Result<R> {
231        self.surface_cleanup_failure()?;
232        let _gate = self.session.gate.read();
233        if !self.record_access || self.session.transaction.lock().is_some() {
234            return Err(SQLiteError::SessionMappingMismatch);
235        }
236        let connection = self
237            .pool
238            .checkout_with_cancellation(Some(control.cancellation()))?;
239        operation(connection.connection()?)
240    }
241
242    pub(crate) fn bind_records(
243        &self,
244        options: VersionedSessionOptions,
245    ) -> Result<Arc<VersionedKeyValueStore>> {
246        self.surface_cleanup_failure()?;
247        let _gate = self.session.gate.write();
248        if let Some(logical) = self.session.logical.get() {
249            if logical.native.is_some() {
250                return Err(SQLiteError::SessionMappingMismatch);
251            }
252            if logical.options().retained_bytes != options.retained_bytes {
253                return Err(SQLiteError::SessionOptionsMismatch);
254            }
255            return Ok(Arc::clone(&logical.store));
256        }
257        if self.session.transaction.lock().is_some() {
258            return Err(SQLiteError::TransactionAlreadyActive);
259        }
260        let identity = self.storage_identity()?;
261        let records = crate::SQLiteRecordStore::for_key_value(
262            self,
263            &StorageReadControl::with_limit(options.retained_bytes),
264        )
265        .map_err(VersionError::into_storage_error)?;
266        let logical = Arc::new(VersionedKeyValueStore::new_with_cancellation(
267            Arc::new(records),
268            identity,
269            options,
270            self.write_cancellation(),
271        ));
272        self.session
273            .logical
274            .set(Arc::new(BoundRecordSession {
275                store: Arc::clone(&logical),
276                native: None,
277            }))
278            .map_err(|_| SQLiteError::SessionOptionsMismatch)?;
279        Ok(logical)
280    }
281
282    pub(crate) fn with_records<R>(
283        &self,
284        operation: impl FnOnce(&VersionedKeyValueStore) -> StorageBackendResult<R>,
285    ) -> StorageBackendResult<R> {
286        self.surface_cleanup_failure()?;
287        let _gate = self.session.gate.read();
288        let logical = self
289            .session
290            .logical
291            .get()
292            .ok_or(SQLiteError::LogicalSessionRequired)?;
293        if logical.native.is_some() {
294            return Err(SQLiteError::SessionMappingMismatch.into());
295        }
296        operation(logical)
297    }
298
299    pub(crate) fn retention_control(
300        &self,
301    ) -> Option<uqa_storage::read_control::StorageReadControl> {
302        self.session
303            .logical
304            .get()
305            .map(|logical| logical.retention_control())
306    }
307
308    pub(crate) fn begin_record_read(&self) -> Result<()> {
309        self.surface_cleanup_failure()?;
310        let _gate = self.session.gate.write();
311        let logical = self
312            .session
313            .logical
314            .get()
315            .ok_or(SQLiteError::LogicalSessionRequired)?;
316        if logical.in_transaction() {
317            return Err(SQLiteError::TransactionAlreadyActive);
318        }
319        logical.begin_read_transaction().map_err(Into::into)
320    }
321
322    /// 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.
323    pub fn refresh_transaction_snapshot(
324        &self,
325        cancellation: &uqa_core::CancellationToken,
326    ) -> Result<()> {
327        self.surface_cleanup_failure()?;
328        let _gate = self.session.gate.write();
329        self.session
330            .logical
331            .get()
332            .ok_or(SQLiteError::LogicalSessionRequired)?
333            .refresh_transaction_snapshot(cancellation)
334            .map_err(Into::into)
335    }
336
337    pub(super) fn check_native_access(&self, connection: &Connection) -> Result<()> {
338        if self.record_access {
339            return Ok(());
340        }
341        let versioned: bool = connection.prepare_cached(
342            "SELECT EXISTS(SELECT 1 FROM sqlite_schema WHERE (name = '_key_value' AND type = 'view') OR name GLOB '_uqa_mvcc_native_*')",
343        )?.query_row([], |row| row.get(0))?;
344        if versioned {
345            return Err(SQLiteError::LogicalSessionRequired);
346        }
347        Ok(())
348    }
349
350    /// 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.
351    pub fn with_physical<R>(&self, operation: impl FnOnce(&Connection) -> Result<R>) -> Result<R> {
352        self.surface_cleanup_failure()?;
353        let _gate = self.session.gate.write();
354        if self.session.transaction.lock().is_some()
355            || self
356                .session
357                .logical
358                .get()
359                .is_some_and(|logical| logical.in_transaction())
360        {
361            return Err(SQLiteError::TransactionAlreadyActive);
362        }
363        let connection = self.pool.checkout()?;
364        operation(connection.connection()?)
365    }
366}
367
368#[cfg(test)]
369mod tests {
370    use super::*;
371    use uqa_storage::mvcc::{CommitErrorOutcome, CommitFailure, DatabaseId, StorageTransactionId};
372    use uqa_storage::StorageBackendError;
373
374    #[test]
375    fn record_checkout_cancellation_does_not_wait_for_a_retained_pool_connection() {
376        use std::{sync::mpsc, thread, time::Duration};
377
378        let connection = ManagedConnection::open_in_memory()
379            .unwrap()
380            .record_connection();
381        let held = connection.pool.checkout().unwrap();
382        let control = StorageReadControl::with_limit(1 << 20);
383        let cancellation = control.cancellation().clone();
384        let (started_tx, started_rx) = mpsc::channel();
385        let (finished_tx, finished_rx) = mpsc::channel();
386        thread::scope(|scope| {
387            let worker = scope.spawn(|| {
388                started_tx.send(()).unwrap();
389                let result = connection.with_record_connection(&control, |_| {
390                    panic!("cancelled checkout must not enter the operation")
391                });
392                finished_tx.send(result).unwrap();
393            });
394            started_rx.recv_timeout(Duration::from_secs(30)).unwrap();
395            cancellation.cancel();
396            let result = finished_rx.recv_timeout(Duration::from_secs(30));
397            drop(held);
398            worker.join().unwrap();
399            assert!(matches!(
400                result.unwrap(),
401                Err::<(), _>(SQLiteError::Cancelled(_))
402            ));
403        });
404    }
405
406    #[test]
407    fn storage_error_conversion_preserves_an_indeterminate_commit_identity() {
408        let transaction = StorageTransactionId::new(DatabaseId::from_bytes([7; 16]), 3).unwrap();
409        let original = StorageBackendError::backend(
410            "MVCC",
411            CommitFailure::Indeterminate {
412                transaction,
413                source: StorageBackendError::Other("commit reply lost".into()),
414            },
415        );
416        let converted = StorageBackendError::from(SQLiteError::from(original));
417        assert_eq!(
418            converted.commit_outcome(),
419            Some(CommitErrorOutcome::Indeterminate(transaction))
420        );
421        let StorageBackendError::Backend { backend, source } = converted else {
422            panic!("typed commit outcome was lost");
423        };
424        assert_eq!(backend, "MVCC");
425        assert!(
426            matches!(source.downcast_ref::<CommitFailure>(), Some(CommitFailure::Indeterminate { transaction: found, .. }) if *found == transaction)
427        );
428    }
429}