1use std::collections::BTreeMap;
4use std::path::Path;
5use std::sync::atomic::{AtomicBool, AtomicU64};
6use std::sync::{Arc, OnceLock};
7
8use crossbeam_queue::ArrayQueue;
9use khive_storage::tx_registry::TxOrigin;
10use khive_storage::CapacityUnavailablePhase;
11use parking_lot::Mutex;
12use rusqlite::Connection;
13use tokio::sync::Semaphore;
14
15use crate::disk_guard_config::{resolve_disk_guard_config, DEFAULT_DISK_GUARD_DEADLINE_MS};
16use crate::error::SqliteError;
17#[cfg(any(unix, windows))]
18use crate::file_identity::database_file_identity;
19
20#[cfg(any(unix, windows))]
21use super::{claimed_file_identity, database_file_identity_if_exists, opened_sqlite_file_identity};
22use super::{
23 code_map, configure_writer_connection, deny_retired_writer, effective_reader_count,
24 initialize_database_id_with_admission, mint_db_identity, open_writer_connection,
25 read_database_id, read_only_open_target, refuse_home_data_store_in_tests,
26 validate_wal_ceiling_at_open, validate_write_admission_deadline, CheckpointOwnershipGate,
27 ConnectionPool, PoolConfig, PoolIdentityRegistration, ReaderAcquisitionCounters,
28 WriteAdmission, WriterAcquisitionCounters,
29};
30#[cfg(test)]
31use super::{run_identity_open_hook, IdentityOpenStage};
32
33enum ReadOnlyOpenMode {
34 FrozenSnapshot,
35 Live,
36}
37
38impl ConnectionPool {
39 pub fn new(config: PoolConfig) -> Result<Self, SqliteError> {
47 Self::new_with_read_only_open_mode(config, ReadOnlyOpenMode::FrozenSnapshot)
48 }
49
50 pub(crate) fn new_read_only_live(mut config: PoolConfig) -> Result<Self, SqliteError> {
51 config.read_only = true;
52 config.write_queue_enabled = Some(false);
53 Self::new_with_read_only_open_mode(config, ReadOnlyOpenMode::Live)
54 }
55
56 fn new_with_read_only_open_mode(
57 config: PoolConfig,
58 read_only_mode: ReadOnlyOpenMode,
59 ) -> Result<Self, SqliteError> {
60 refuse_home_data_store_in_tests(&config)?;
61 validate_write_admission_deadline(config.write_admission_deadline_ms)?;
62 if let Some(policy) = config.disk_guard_config {
63 policy.validate()?;
64 }
65 config.wal_ceiling.validate_static(
66 config.path.is_some(),
67 config.wal_mode,
68 config.read_only,
69 )?;
70 code_map::validate_pool(&config)?;
71 if config.path.is_some() && !config.read_only {
72 let lock_dir =
73 crate::disk_guard_config::require_volume_lock_dir(config.volume_lock_dir.clone())?;
74 if !lock_dir.is_absolute() {
75 return Err(SqliteError::CapacityUnavailable {
76 phase: CapacityUnavailablePhase::Lock,
77 message: "configured volume-lock directory is not absolute".to_string(),
78 });
79 }
80 }
81
82 let mut config = config;
86 let inert_memory_queue_request =
87 config.path.is_none() && config.write_queue_enabled == Some(true);
88 config.write_queue_enabled =
89 Some(config.write_queue_enabled.unwrap_or(config.path.is_some()));
90 if inert_memory_queue_request {
91 tracing::warn!(target: "khive_db::pool",
92 "write queue explicitly requested for an in-memory pool; it is inert because \
93 in-memory pools cannot host a writer task"
94 );
95 }
96
97 let (origin, identity_path) = match config.path.as_ref() {
102 Some(path) if config.code_map_vfs.is_some() => code_map::guarded_identity(path),
103 Some(path) => {
104 let (identity, canonical) = mint_db_identity(path)?;
105 (TxOrigin::Database(identity), Some(canonical))
106 }
107 None => (TxOrigin::Memory, None),
108 };
109 let (write_admission, disk_guard_config) = if !config.read_only {
110 if identity_path.as_deref().and_then(Path::parent).is_some() {
111 let disk_guard = match config.disk_guard_config {
112 Some(policy) => policy,
113 None => resolve_disk_guard_config(None, None)?,
114 };
115 disk_guard.validate()?;
116 if disk_guard.legacy_environment_present {
117 tracing::warn!(target: "khive_db::pool",
118 "legacy SQLite reserve setting is deprecated; \
119 use KHIVE_SQLITE_DISK_RESERVE_BYTES"
120 );
121 }
122 if disk_guard.reserve_bytes == 0 {
123 tracing::warn!(target: "khive_db::pool",
124 "SQLite disk reserve is explicitly zero; \
125 new logical writes will not be floor-refused"
126 );
127 }
128 (
129 Arc::new(WriteAdmission::new(
130 identity_path.clone(),
131 disk_guard.reserve_bytes,
132 disk_guard.guard_deadline_ms,
133 config.volume_lock_dir.clone(),
134 )?),
135 Some(disk_guard),
136 )
137 } else {
138 (
139 Arc::new(WriteAdmission::new(
140 None,
141 0,
142 DEFAULT_DISK_GUARD_DEADLINE_MS,
143 None,
144 )?),
145 None,
146 )
147 }
148 } else {
149 (
150 Arc::new(WriteAdmission::new(
151 None,
152 0,
153 DEFAULT_DISK_GUARD_DEADLINE_MS,
154 None,
155 )?),
156 None,
157 )
158 };
159 let read_only_open_target = match read_only_mode {
160 ReadOnlyOpenMode::FrozenSnapshot => {
161 read_only_open_target(&config, identity_path.as_deref())?
162 }
163 ReadOnlyOpenMode::Live => identity_path.clone(),
166 };
167 #[cfg(any(unix, windows))]
168 let identity_before_open = identity_path
169 .as_deref()
170 .map(database_file_identity_if_exists)
171 .transpose()?
172 .flatten();
173 #[cfg(any(unix, windows))]
174 claimed_file_identity::verify_before_open(&config, identity_before_open)?;
175 let retirement_connection = Connection::open_in_memory()?;
176 retirement_connection.authorizer(Some(deny_retired_writer))?;
177 let mut initialization_lease = None;
179 let mut writer = open_writer_connection(
180 &config,
181 read_only_open_target.as_deref(),
182 identity_path.as_deref(),
183 )?;
184 validate_wal_ceiling_at_open(&writer, &config)?;
185 writer.busy_timeout(config.busy_timeout)?;
188 let initial_database_id = if identity_path.is_some() {
192 read_database_id(&writer)?
193 } else {
194 None
195 };
196 #[cfg(test)]
197 if let Some(path) = identity_path.as_deref() {
198 run_identity_open_hook(
199 path,
200 IdentityOpenStage::AfterMainOpenBeforeFirstStat,
201 Some(&writer),
202 );
203 }
204 #[cfg(any(unix, windows))]
205 let identity_before_write = identity_path
206 .as_deref()
207 .map(database_file_identity)
208 .transpose()?;
209 #[cfg(any(unix, windows))]
210 if identity_before_open.is_some() && identity_before_open != identity_before_write {
211 return Err(SqliteError::InvalidData(
212 "database file identity changed while opening the pool".to_string(),
213 ));
214 }
215 #[cfg(any(unix, windows))]
216 if let Some(path) = identity_path.as_deref() {
217 let opened = opened_sqlite_file_identity(&writer, path)?;
218 if identity_before_write != Some(opened) {
219 return Err(SqliteError::InvalidData(
220 "database file identity changed while opening the pool".to_string(),
221 ));
222 }
223 }
224 write_admission.verify_current_volume()?;
227 let opened_database_id = if identity_path.is_some()
228 && !config.read_only
229 && initial_database_id.is_none()
230 {
231 match write_admission.check() {
232 Ok(()) => {
233 initialization_lease = write_admission.acquire()?;
234 match initialize_database_id_with_admission(&mut writer, Some(&write_admission))
235 {
236 Ok(id) => Some(id),
237 Err(SqliteError::CapacityFloor { .. }) => None,
238 Err(error) => return Err(error),
239 }
240 }
241 Err(SqliteError::CapacityFloor { .. }) => None,
245 Err(error) => return Err(error),
246 }
247 } else {
248 initial_database_id
249 };
250 drop(initialization_lease.take());
251 #[cfg(test)]
252 if let Some(path) = identity_path.as_deref() {
253 run_identity_open_hook(
254 path,
255 IdentityOpenStage::AfterInitialIdentityWrite,
256 Some(&writer),
257 );
258 }
259 #[cfg(any(unix, windows))]
260 let opened_file_identity = identity_path
261 .as_deref()
262 .map(|path| opened_sqlite_file_identity(&writer, path))
263 .transpose()?;
264 #[cfg(any(unix, windows))]
265 if identity_before_write != opened_file_identity {
266 return Err(SqliteError::InvalidData(
267 "database file identity changed while opening the pool".to_string(),
268 ));
269 }
270 let wal_enabled = configure_writer_connection(&writer, &config)?;
271 let max_readers = effective_reader_count(&config, wal_enabled);
272
273 let readers = ArrayQueue::new(max_readers.max(1));
274
275 #[cfg(any(test, feature = "test-support"))]
276 let statement_observer = crate::statement_observer::StatementObserverHub::new()?;
277 #[cfg(any(test, feature = "test-support"))]
278 crate::statement_observer::install(&writer, &statement_observer)?;
279
280 let mut pool = Self {
281 writer: Arc::new(Mutex::new(writer)),
282 retirement_connection: Mutex::new(Some(retirement_connection)),
283 #[cfg(any(test, feature = "test-support"))]
284 statement_observer,
285 main_pool_generation: OnceLock::new(),
286 checkpoint_ownership: CheckpointOwnershipGate::new(),
287 pooled_writer_retired: AtomicBool::new(false),
288 writer_acquisition_counters: Arc::new(WriterAcquisitionCounters::default()),
289 write_admission,
290 disk_guard_config,
291 reader_acquisition_counters: ReaderAcquisitionCounters::default(),
292 note_search_routes: Default::default(),
293 reader_checkouts: Mutex::new(BTreeMap::new()),
294 search_dispatches: Mutex::new(BTreeMap::new()),
295 note_candidate_hydration_rows: AtomicU64::new(0),
296 readers,
297 max_readers,
298 config,
299 read_only_open_target,
300 sql_bridge_reader_slots: Arc::new(Semaphore::new(max_readers.max(1))),
301 sql_bridge_writer_slots: Arc::new(Semaphore::new(1)),
302 writer_task: OnceLock::new(),
303 writer_task_join: Mutex::new(None),
304 writer_task_join_stored: AtomicBool::new(false),
305 origin,
306 identity_path,
307 #[cfg(any(unix, windows))]
308 opened_file_identity,
309 opened_database_id,
310 identity_registration: None,
311 timeout_sink_registration: None,
312 #[cfg(test)]
313 writer_task_spawn_count: std::sync::atomic::AtomicUsize::new(0),
314 };
315
316 for _ in 0..pool.max_readers {
317 let conn = pool.open_pooled_reader()?;
318 pool.readers
319 .push(conn)
320 .expect("reader queue must have capacity during pool initialization");
321 }
322
323 if !pool.config.read_only {
326 pool.timeout_sink_registration = crate::timeout_sink::init(
327 pool.canonical_path().and_then(Path::parent),
328 &crate::timeout_sink::db_label(&pool),
329 )?;
330 }
331
332 pool.identity_registration = pool.canonical_path().map(PoolIdentityRegistration::new);
333 Ok(pool)
334 }
335}