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