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.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 pub fn write_cancellation(&self) -> uqa_core::CancellationToken {
191 self.session.write_cancellation.clone()
192 }
193
194 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 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 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 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}