1mod acquisition;
3mod connection_setup;
4mod construction;
5#[cfg(test)]
6mod external_writer_fixture;
7mod guards;
8mod identity;
9mod note_search_routes;
10mod pool_impl;
11mod reader_counters;
12mod standalone_checkpoint;
13#[cfg(test)]
14pub(crate) use external_writer_fixture::open_external_writer_fixture;
15
16pub(crate) use connection_setup::open_read_only_snapshot_connection;
17#[cfg(feature = "namespace-trigram-proto")]
18use connection_setup::register_namespace_trigram;
19#[cfg(test)]
20use connection_setup::sqlite_header_uses_wal;
21use connection_setup::{
22 close_connection_quietly, configure_reader_connection, configure_writer_connection,
23 current_journal_mode, effective_reader_count, open_reader_connection, open_writer_connection,
24 pool_exhausted_error, read_only_open_target, reader_connection_is_healthy,
25 reset_reader_connection, restore_shared_reader_state, validate_wal_ceiling_at_open,
26 writer_open_flags, writer_read_only_open_flags,
27};
28#[cfg(any(unix, windows))]
29use identity::database_file_identity_if_exists;
30#[cfg(test)]
31use identity::initialize_database_id;
32#[cfg(any(unix, windows))]
33pub(crate) use identity::opened_sqlite_file_identity;
34use identity::{initialize_database_id_with_admission, mint_db_identity, read_database_id};
35
36pub use crate::timeout_sink::{TimeoutSinkCloseError, TimeoutSinkCloseHandle};
37use guards::{PooledReader, ReaderLease};
38pub(crate) use guards::{ReaderAdmission, SharedReaderTransactionGuard};
39pub use guards::{ReaderGuard, ReaderRow};
40use note_search_routes::NoteSearchRouteCounters;
41pub use note_search_routes::{NoteSearchFallbackCause, NoteSearchRouteSnapshot};
42use reader_counters::ReaderAcquisitionCounters;
43pub use reader_counters::ReaderAcquisitionSnapshot;
44pub(crate) use reader_counters::StandaloneReaderPurpose;
45pub(crate) use standalone_checkpoint::CheckpointFile;
46pub use standalone_checkpoint::StandaloneCheckpoint;
47
48mod code_map;
49mod sql_functions;
50#[cfg(test)]
51pub(crate) use sql_functions::register_rfc3339_key;
52use sql_functions::{register_read_functions, register_writer_clock};
53pub(crate) use sql_functions::{rfc3339_instant_key, strict_rfc3339_key};
54#[path = "pool/identity_registry.rs"]
55mod identity_registry;
56#[cfg(any(test, feature = "test-support"))]
57#[path = "pool/test_volume_lock_dir.rs"]
58mod test_volume_lock_dir;
59#[path = "pool/write_units.rs"]
60mod write_units;
61#[path = "pool/writer_acquisition.rs"]
62mod writer_acquisition;
63#[cfg(test)]
64use identity_registry::pool_identity_suffix;
65use identity_registry::PoolIdentityRegistration;
66#[cfg(any(test, feature = "test-support"))]
67use test_volume_lock_dir::test_volume_lock_dir;
68#[cfg(test)]
69use write_units::STARTUP_SPACE_PROBE;
70pub use write_units::{CheckpointGuard, CheckpointResult, WriterAcquisitionSnapshot, WriterGuard};
71pub(crate) use write_units::{
72 PooledAutocommitWriteUnit, PooledTransactionWriteUnit, StandaloneWriteUnit, WriteAdmission,
73 WriterAcquisitionCounters,
74};
75
76use crossbeam_queue::ArrayQueue;
77use parking_lot::{Condvar, Mutex};
78use rusqlite::hooks::{AuthContext, Authorization};
79use rusqlite::{Connection, OpenFlags};
80use serde::Serialize;
81use sha2::{Digest, Sha256};
82#[cfg(test)]
83use std::cell::Cell;
84use std::collections::{BTreeMap, HashMap};
85use std::fs;
86use std::path::{Path, PathBuf};
87use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
88use std::sync::{Arc, OnceLock};
89#[cfg(test)]
90use std::thread;
91use std::time::{Duration, Instant};
92use tokio::sync::Semaphore;
93
94#[cfg(test)]
95use crate::database_owner_identity::DatabaseOwnerIdentityError;
96use crate::disk_guard::{LeaseRefusal, VolumeIdentity, VolumeLease};
97use crate::disk_guard_config::{EffectiveDiskGuardConfig, DEFAULT_DISK_GUARD_DEADLINE_MS};
98use crate::error::SqliteError;
99#[cfg(all(test, any(unix, windows)))]
100use crate::file_identity::database_file_identity;
101#[cfg(any(unix, windows))]
102use crate::file_identity::DatabaseFileIdentity;
103use crate::writer_task::{execute_wrapped_transaction, WriterTaskHandle};
104use khive_storage::error::StorageError;
105use khive_storage::tx_registry::TxOrigin;
106use khive_storage::CapacityUnavailablePhase;
107use khive_storage::StorageCapability;
108
109mod claimed_file_identity;
110
111#[cfg(unix)]
112mod claimed_file_observer;
113
114#[cfg(unix)]
115pub use claimed_file_observer::initialize as initialize_claimed_file_observer;
116
117#[cfg(all(test, unix))]
118#[path = "pool/claimed_file_identity_tests.rs"]
119mod claimed_file_identity_tests;
120
121pub(crate) const DEFAULT_SQLITE_CACHE_KIB: i64 = 8 * 1024;
130pub(crate) const SQLITE_CACHE_KIB_RANGE: std::ops::RangeInclusive<i64> = 512..=1_048_576;
131const SQLITE_CACHE_KIB_ENV: &str = "KHIVE_SQLITE_CACHE_KIB";
132
133pub(crate) const DEFAULT_SQLITE_MMAP_BYTES: i64 = 1 << 30;
140pub(crate) const SQLITE_MMAP_BYTES_RANGE: std::ops::RangeInclusive<i64> = 0..=(1 << 40);
141const SQLITE_MMAP_BYTES_ENV: &str = "KHIVE_SQLITE_MMAP_BYTES";
142const DEFAULT_READER_CAP: usize = 8;
143
144pub(crate) fn sqlite_cache_size_pragma() -> i64 {
147 static KIB: OnceLock<i64> = OnceLock::new();
148 -*KIB.get_or_init(|| {
149 sqlite_size_setting(
150 SQLITE_CACHE_KIB_ENV,
151 sqlite_size_env(SQLITE_CACHE_KIB_ENV).as_deref(),
152 DEFAULT_SQLITE_CACHE_KIB,
153 &SQLITE_CACHE_KIB_RANGE,
154 )
155 })
156}
157
158pub(crate) fn sqlite_mmap_size_pragma() -> i64 {
161 static BYTES: OnceLock<i64> = OnceLock::new();
162 *BYTES.get_or_init(|| {
163 sqlite_size_setting(
164 SQLITE_MMAP_BYTES_ENV,
165 sqlite_size_env(SQLITE_MMAP_BYTES_ENV).as_deref(),
166 DEFAULT_SQLITE_MMAP_BYTES,
167 &SQLITE_MMAP_BYTES_RANGE,
168 )
169 })
170}
171
172fn sqlite_size_env(name: &str) -> Option<String> {
176 std::env::var_os(name).map(|raw| raw.to_string_lossy().into_owned())
177}
178
179pub(crate) fn sqlite_size_setting(
183 name: &str,
184 raw: Option<&str>,
185 default: i64,
186 range: &std::ops::RangeInclusive<i64>,
187) -> i64 {
188 let Some(raw) = raw else {
189 return default;
190 };
191 match raw.parse::<i64>() {
192 Ok(value) if range.contains(&value) => value,
193 _ => {
194 tracing::warn!(
195 setting = name,
196 value = raw,
197 default,
198 min = *range.start(),
199 max = *range.end(),
200 "ignoring a SQLite size setting outside its range; using the default"
201 );
202 default
203 }
204 }
205}
206
207const DEFAULT_JOURNAL_SIZE_LIMIT_BYTES: i64 = 67_108_864; const DEFAULT_WRITE_QUEUE_CAPACITY: usize = 256;
209const DATABASE_ID_TABLE: &str = "_khive_database_identity";
210static NEXT_MAIN_POOL_GENERATION: AtomicU64 = AtomicU64::new(1);
211
212#[cfg(test)]
213#[derive(Clone, Copy, PartialEq, Eq)]
214enum IdentityOpenStage {
215 AfterMainOpenBeforeFirstStat,
216 AfterInitialIdentityWrite,
217 BeforeStandaloneOpen,
218 AfterStandaloneOpen,
219}
220
221#[cfg(test)]
222type IdentityOpenHook = Box<dyn Fn(&Path, IdentityOpenStage, Option<&Connection>)>;
223
224#[cfg(test)]
225thread_local! {
226 static IDENTITY_OPEN_HOOK: std::cell::RefCell<Option<IdentityOpenHook>> =
227 const { std::cell::RefCell::new(None) };
228}
229
230#[cfg(test)]
231fn run_identity_open_hook(path: &Path, stage: IdentityOpenStage, conn: Option<&Connection>) {
232 IDENTITY_OPEN_HOOK.with(|hook| {
233 if let Some(hook) = hook.borrow().as_ref() {
234 hook(path, stage, conn);
235 }
236 });
237}
238
239#[path = "pool/admission.rs"]
240mod admission;
241use admission::CheckpointOwnershipGate;
242pub use admission::RuntimeWriteOperation;
243pub(crate) use admission::FALLBACK_WAL_AUTOCHECKPOINT_PAGES;
244#[cfg(test)]
245use admission::{CheckpointConnectionConfigPause, CheckpointOwnership};
246
247fn deny_retired_writer(_context: AuthContext<'_>) -> Authorization {
248 Authorization::Deny
249}
250
251mod config;
252
253pub(crate) use config::TEST_HARNESS_ENV;
254use config::{refuse_home_data_store_in_tests, validate_write_admission_deadline};
255pub use config::{PoolConfig, WalCeilingPolicy, WalCeilingSource};
256
257#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize)]
259pub struct SearchMechanismSnapshot {
260 pub dispatches_by_backend_and_kind: BTreeMap<String, BTreeMap<String, u64>>,
264 pub note_candidate_hydration_rows: u64,
268}
269
270pub struct ConnectionPool {
284 writer: Arc<Mutex<Connection>>,
285 retirement_connection: Mutex<Option<Connection>>,
287 #[cfg(any(test, feature = "test-support"))]
288 statement_observer: Arc<crate::statement_observer::StatementObserverHub>,
289 main_pool_generation: OnceLock<u64>,
290 checkpoint_ownership: CheckpointOwnershipGate,
299 pooled_writer_retired: AtomicBool,
304 writer_acquisition_counters: Arc<WriterAcquisitionCounters>,
309 write_admission: Arc<WriteAdmission>,
312 disk_guard_config: Option<EffectiveDiskGuardConfig>,
315 reader_acquisition_counters: ReaderAcquisitionCounters,
320 note_search_routes: NoteSearchRouteCounters,
322 reader_checkouts: Mutex<BTreeMap<Instant, usize>>,
323 search_dispatches: Mutex<BTreeMap<String, BTreeMap<String, u64>>>,
326 note_candidate_hydration_rows: AtomicU64,
327 readers: ArrayQueue<Box<PooledReader>>,
328 max_readers: usize,
329 config: PoolConfig,
330 read_only_open_target: Option<PathBuf>,
338 sql_bridge_reader_slots: Arc<Semaphore>,
339 sql_bridge_writer_slots: Arc<Semaphore>,
340 writer_task: OnceLock<Option<WriterTaskHandle>>,
345 writer_task_join: Mutex<Option<tokio::task::JoinHandle<()>>>,
353 writer_task_join_stored: AtomicBool,
358 origin: TxOrigin,
364 identity_path: Option<PathBuf>,
370 #[cfg(any(unix, windows))]
373 opened_file_identity: Option<DatabaseFileIdentity>,
374 opened_database_id: Option<uuid::Uuid>,
377 identity_registration: Option<PoolIdentityRegistration>,
380 timeout_sink_registration: Option<crate::timeout_sink::Registration>,
382 #[cfg(test)]
388 writer_task_spawn_count: std::sync::atomic::AtomicUsize,
389}
390
391impl Drop for ConnectionPool {
392 fn drop(&mut self) {
400 while let Some(conn) = self.readers.pop() {
401 drop(conn);
402 }
403 }
404}
405
406#[cfg(test)]
407#[path = "runtime_write_routing_tests.rs"]
408mod runtime_write_routing_tests;
409
410#[cfg(test)]
411#[path = "database_owner_identity_pool_tests.rs"]
412mod database_owner_identity_pool_tests;
413
414#[cfg(test)]
415#[path = "pool_tests.rs"]
416mod tests;
417
418#[cfg(test)]
419#[path = "pool/recycling_tests.rs"]
420mod recycling_tests;
421
422#[cfg(all(test, any(unix, windows)))]
423#[path = "pool_identity_admission_tests.rs"]
424mod identity_admission_tests;