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 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 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(®istry)));
109 Ok(registry)
110 }
111
112 #[must_use]
116 pub fn new_session(&self) -> Self {
117 self.new_session_with_cancellation(&uqa_core::CancellationToken::new())
118 }
119
120 #[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 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 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 pub fn write_cancellation(&self) -> uqa_core::CancellationToken {
226 self.session.write_cancellation.clone()
227 }
228
229 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 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 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 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}