Skip to main content

graphd_engine/
engine.rs

1//! Engine: per-database concurrency control layer.
2//!
3//! Wraps a `Backend` with:
4//! - Read semaphore (N concurrent reads)
5//! - Write mutex (1 serialized write at a time, auto-journaled)
6//! - Snapshot lock (shared across reads/writes, exclusive for CHECKPOINT)
7//! - Optional statement-level sandboxing
8//!
9//! Uses `tokio::spawn_blocking` from the shared thread pool — zero threads when idle,
10//! scales across many databases in a multi-tenant process.
11
12use std::sync::{Arc, RwLock};
13
14use crate::backend::Backend;
15use crate::error::GraphdError;
16use crate::journal_types::{self as journal, JournalSender};
17use crate::query::{self, ExecutedQuery};
18
19use crate::sandbox::SandboxConfig;
20
21/// Per-database query execution engine with concurrency control.
22pub struct Engine {
23    backend: Arc<Backend>,
24    snapshot_lock: Arc<RwLock<()>>,
25    journal: Option<JournalSender>,
26    sandbox: Option<Arc<SandboxConfig>>,
27    read_semaphore: tokio::sync::Semaphore,
28    write_mutex: tokio::sync::Mutex<()>,
29}
30
31impl Engine {
32    /// Create a new Engine wrapping the given backend.
33    ///
34    /// - `num_readers`: max concurrent read queries (semaphore permits)
35    /// - `journal`: optional journal sender for write-ahead logging
36    /// - `sandbox`: optional statement-level sandbox for multi-tenant safety
37    pub fn new(
38        backend: Arc<Backend>,
39        num_readers: usize,
40        journal: Option<JournalSender>,
41        sandbox: Option<SandboxConfig>,
42    ) -> Self {
43        Self {
44            backend,
45            snapshot_lock: Arc::new(RwLock::new(())),
46            journal,
47            sandbox: sandbox.map(Arc::new),
48            read_semaphore: tokio::sync::Semaphore::new(num_readers),
49            write_mutex: tokio::sync::Mutex::new(()),
50        }
51    }
52
53    /// Execute an auto-commit query, routing reads vs writes automatically.
54    ///
55    /// - Reads: bounded by semaphore (up to N concurrent).
56    /// - Writes: serialized by mutex (1 at a time), auto-journaled on success.
57    ///
58    /// If a sandbox is configured, queries are checked before execution.
59    pub async fn execute(
60        &self,
61        query: String,
62        params: Option<serde_json::Value>,
63    ) -> Result<ExecutedQuery, GraphdError> {
64        // Sandbox check: prepare the query and verify the statement type is allowed.
65        if let Some(ref sandbox) = self.sandbox {
66            let backend = self.backend.clone();
67            let q = query.clone();
68            let sandbox = sandbox.clone();
69            tokio::task::spawn_blocking(move || {
70                let conn = backend.connection()?;
71                sandbox.check_query(&conn, &q)
72            })
73            .await
74            .map_err(|e| GraphdError::DatabaseError(format!("Task panicked: {e}")))?
75            ?;
76        }
77
78        if journal::is_mutation(&query) {
79            self.execute_write(query, params).await
80        } else {
81            self.execute_read(query, params).await
82        }
83    }
84
85    async fn execute_read(
86        &self,
87        query: String,
88        params: Option<serde_json::Value>,
89    ) -> Result<ExecutedQuery, GraphdError> {
90        let _permit = self
91            .read_semaphore
92            .acquire()
93            .await
94            .map_err(|_| GraphdError::DatabaseUnavailable("Engine closed".into()))?;
95        let backend = self.backend.clone();
96        let lock = self.snapshot_lock.clone();
97        tokio::task::spawn_blocking(move || {
98            let conn = backend.connection()?;
99            let _guard = lock.read().unwrap_or_else(|e| e.into_inner());
100            query::run_query(&conn, &query, params.as_ref())
101        })
102        .await
103        .map_err(|e| GraphdError::DatabaseError(format!("Task panicked: {e}")))?
104    }
105
106    async fn execute_write(
107        &self,
108        query: String,
109        params: Option<serde_json::Value>,
110    ) -> Result<ExecutedQuery, GraphdError> {
111        let _guard = self.write_mutex.lock().await;
112        let backend = self.backend.clone();
113        let lock = self.snapshot_lock.clone();
114        let journal = self.journal.clone();
115        tokio::task::spawn_blocking(move || {
116            let conn = backend.connection()?;
117            let _snap = lock.read().unwrap_or_else(|e| e.into_inner());
118            let result = query::run_query(&conn, &query, params.as_ref());
119            if let Ok(ref eq) = result {
120                query::journal_entry(&journal, &eq.rewritten_query, &eq.merged_params);
121            }
122            result
123        })
124        .await
125        .map_err(|e| GraphdError::DatabaseError(format!("Task panicked: {e}")))?
126    }
127
128    /// Create a dedicated connection for Bolt sessions and HTTP transactions.
129    /// The caller owns the connection for its lifetime.
130    pub fn connection(&self) -> Result<lbug::Connection<'_>, GraphdError> {
131        self.backend.connection()
132    }
133
134    /// Snapshot lock — take a read lock for queries, write lock for CHECKPOINT.
135    pub fn snapshot_lock(&self) -> &Arc<RwLock<()>> {
136        &self.snapshot_lock
137    }
138
139    /// Journal sender (None if journaling is disabled).
140    pub fn journal(&self) -> &Option<JournalSender> {
141        &self.journal
142    }
143
144    /// Underlying backend (for snapshot creation and restore paths).
145    pub fn backend(&self) -> &Arc<Backend> {
146        &self.backend
147    }
148
149    /// Sandbox config (for manual query checks in Bolt transaction mode).
150    pub fn sandbox(&self) -> Option<&Arc<SandboxConfig>> {
151        self.sandbox.as_ref()
152    }
153
154    /// Acquire exclusive write access (blocking).
155    ///
156    /// Use from `spawn_blocking` contexts (Bolt sessions, HTTP transaction workers).
157    /// For async contexts, use `execute()` which acquires the lock internally.
158    ///
159    /// Hold the guard for the duration of a write transaction (BEGIN→COMMIT),
160    /// or for a single auto-commit mutation.
161    pub fn acquire_writer(&self) -> tokio::sync::MutexGuard<'_, ()> {
162        self.write_mutex.blocking_lock()
163    }
164}
165
166#[cfg(test)]
167mod tests {
168    use super::*;
169    use std::path::Path;
170
171    fn temp_engine(dir: &Path, num_readers: usize) -> Engine {
172        let db_path = dir.join("db");
173        let backend = Arc::new(Backend::open(&db_path).unwrap());
174        Engine::new(backend, num_readers, None, None)
175    }
176
177    fn temp_engine_sandboxed(dir: &Path) -> Engine {
178        let db_path = dir.join("db");
179        let backend = Arc::new(Backend::open(&db_path).unwrap());
180        let sandbox = SandboxConfig::multi_tenant();
181        Engine::new(backend, 4, None, Some(sandbox))
182    }
183
184    #[tokio::test]
185    async fn read_query_through_pool() {
186        let dir = tempfile::tempdir().unwrap();
187        let engine = temp_engine(dir.path(), 4);
188        let result = engine
189            .execute("RETURN 1 AS n".to_string(), None)
190            .await
191            .unwrap();
192        assert_eq!(result.columns, vec!["n"]);
193        assert_eq!(result.rows.len(), 1);
194    }
195
196    #[tokio::test]
197    async fn write_query_through_pool() {
198        let dir = tempfile::tempdir().unwrap();
199        let engine = temp_engine(dir.path(), 4);
200
201        engine
202            .execute(
203                "CREATE NODE TABLE EngTest(val STRING, PRIMARY KEY(val))".to_string(),
204                None,
205            )
206            .await
207            .unwrap();
208        engine
209            .execute(
210                "CREATE (:EngTest {val: 'hello'})".to_string(),
211                None,
212            )
213            .await
214            .unwrap();
215
216        let result = engine
217            .execute(
218                "MATCH (e:EngTest) RETURN e.val".to_string(),
219                None,
220            )
221            .await
222            .unwrap();
223        assert_eq!(result.rows.len(), 1);
224    }
225
226    #[tokio::test]
227    async fn concurrent_reads() {
228        let dir = tempfile::tempdir().unwrap();
229        let engine = Arc::new(temp_engine(dir.path(), 4));
230
231        let mut handles = Vec::new();
232        for _ in 0..20 {
233            let eng = engine.clone();
234            handles.push(tokio::spawn(async move {
235                eng.execute("RETURN 1 AS n".to_string(), None).await
236            }));
237        }
238
239        for h in handles {
240            let result = h.await.unwrap().unwrap();
241            assert_eq!(result.rows.len(), 1);
242        }
243    }
244
245    #[tokio::test]
246    async fn mutation_routing() {
247        let dir = tempfile::tempdir().unwrap();
248        let engine = temp_engine(dir.path(), 4);
249
250        engine
251            .execute(
252                "CREATE NODE TABLE MutTest(val INT64, PRIMARY KEY(val))".to_string(),
253                None,
254            )
255            .await
256            .unwrap();
257        engine
258            .execute("CREATE (:MutTest {val: 42})".to_string(), None)
259            .await
260            .unwrap();
261
262        let result = engine
263            .execute("MATCH (m:MutTest) RETURN m.val".to_string(), None)
264            .await
265            .unwrap();
266        assert_eq!(result.rows.len(), 1);
267    }
268
269    #[tokio::test]
270    async fn dedicated_connection() {
271        let dir = tempfile::tempdir().unwrap();
272        let engine = temp_engine(dir.path(), 4);
273
274        let conn = engine.connection().unwrap();
275        let result = conn.query("RETURN 1").unwrap();
276        let cols = result.get_column_names();
277        assert_eq!(cols.len(), 1);
278    }
279
280    #[tokio::test]
281    async fn snapshot_lock_blocks_queries() {
282        let dir = tempfile::tempdir().unwrap();
283        let engine = Arc::new(temp_engine(dir.path(), 4));
284
285        let lock = engine.snapshot_lock().clone();
286        let _guard = lock.write().unwrap();
287
288        let eng = engine.clone();
289        let handle = tokio::spawn(async move {
290            eng.execute("RETURN 1 AS n".to_string(), None).await
291        });
292
293        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
294        assert!(!handle.is_finished());
295
296        drop(_guard);
297        let result = handle.await.unwrap().unwrap();
298        assert_eq!(result.rows.len(), 1);
299    }
300
301    #[tokio::test]
302    async fn sandboxed_allows_read() {
303        let dir = tempfile::tempdir().unwrap();
304        let engine = temp_engine_sandboxed(dir.path());
305        let result = engine.execute("RETURN 1 AS n".to_string(), None).await;
306        assert!(result.is_ok(), "Read queries should be allowed");
307    }
308
309    #[tokio::test]
310    async fn sandboxed_allows_schema() {
311        let dir = tempfile::tempdir().unwrap();
312        let engine = temp_engine_sandboxed(dir.path());
313        let result = engine
314            .execute(
315                "CREATE NODE TABLE SandboxTest(id INT64, PRIMARY KEY(id))".to_string(),
316                None,
317            )
318            .await;
319        assert!(result.is_ok(), "Schema creation should be allowed");
320    }
321
322    #[tokio::test]
323    async fn sandboxed_blocks_copy_from() {
324        let dir = tempfile::tempdir().unwrap();
325        let engine = temp_engine_sandboxed(dir.path());
326
327        // Create a table first so COPY FROM parses
328        engine
329            .execute(
330                "CREATE NODE TABLE CopyTest(id INT64, PRIMARY KEY(id))".to_string(),
331                None,
332            )
333            .await
334            .unwrap();
335
336        // COPY FROM is blocked either by the sandbox (type check) or by lbug's binder
337        // (file format validation). Either way, the query must not execute.
338        let result = engine
339            .execute("COPY CopyTest FROM '/etc/passwd'".to_string(), None)
340            .await;
341        assert!(result.is_err(), "COPY FROM should be blocked");
342    }
343}