uqa_storage_sqlite/connection/
logical.rs1use 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 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 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(®istry)));
118 Ok(registry)
119 }
120
121 #[must_use]
125 pub fn new_session(&self) -> Self {
126 self.new_session_with_cancellation(&uqa_core::CancellationToken::new())
127 }
128
129 #[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 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 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 pub fn write_cancellation(&self) -> uqa_core::CancellationToken {
235 self.session.write_cancellation.clone()
236 }
237
238 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 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 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 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}