surrealdb_engine_local/
lib.rs1#![recursion_limit = "256"]
19#![allow(clippy::absolute_paths)]
21
22#[macro_use]
23extern crate tracing;
24
25use std::future::Future;
26use std::path::PathBuf;
27use std::sync::Arc;
28use std::time::Duration;
29
30use async_channel::Receiver;
31use surrealdb_cnf::ConfigMap;
32#[doc(inline)]
33pub use surrealdb_core::kvs::Datastore;
34#[doc(inline)]
35pub use surrealdb_core::options::EngineOptions;
36use surrealdb_engine_api::SessionId;
37use surrealdb_rpc::capabilities::Capabilities;
38use surrealdb_types::{Error, Notification};
39
40mod engine;
41mod session;
42
43#[doc(inline)]
48pub use surrealdb_core::kvs::tasks;
49
50pub use crate::engine::LocalEngine;
51use crate::session::SessionRegistry;
52
53#[derive(Debug, Clone)]
55pub struct Root {
56 pub username: String,
58 pub password: String,
60}
61
62#[derive(Debug, Clone, Default)]
67pub struct LocalConfig {
68 pub path: String,
71 pub root: Option<Root>,
74 pub query_timeout: Option<Duration>,
76 pub transaction_timeout: Option<Duration>,
78 pub capabilities: Capabilities,
80 pub bucket_folder_allowlist: Vec<PathBuf>,
83 pub temporary_directory: Option<PathBuf>,
86 pub node_membership_refresh_interval: Option<Duration>,
89 pub node_membership_check_interval: Option<Duration>,
91 pub node_membership_cleanup_interval: Option<Duration>,
93 pub changefeed_gc_interval: Option<Duration>,
95 pub datastore_options: Vec<(String, String)>,
101}
102
103impl LocalConfig {
104 fn engine_options(&self) -> EngineOptions {
107 let mut opt = EngineOptions::default();
108 if let Some(interval) = self.node_membership_refresh_interval {
109 opt.node_membership_refresh_interval = interval;
110 }
111 if let Some(interval) = self.node_membership_check_interval {
112 opt.node_membership_check_interval = interval;
113 }
114 if let Some(interval) = self.node_membership_cleanup_interval {
115 opt.node_membership_cleanup_interval = interval;
116 }
117 if let Some(interval) = self.changefeed_gc_interval {
118 opt.changefeed_gc_interval = interval;
119 }
120 opt
121 }
122
123 fn datastore_config(&self) -> Result<ConfigMap, Error> {
129 let mut map = ConfigMap::empty();
130 for (key, value) in &self.datastore_options {
131 let key = key.to_lowercase();
133 if key == "bucket_folder_allowlist" {
134 return Err(std_error_to_types_error(
135 "the bucket folder allowlist is set by its own option, not as a datastore option",
136 ));
137 }
138 map = map.with_key_value(key, value.clone());
139 }
140 if !self.bucket_folder_allowlist.is_empty() {
141 let joined = std::env::join_paths(&self.bucket_folder_allowlist)
144 .map_err(|e| {
145 std_error_to_types_error(format!("invalid bucket folder allowlist: {e}"))
146 })?
147 .into_string()
148 .map_err(|_| {
149 std_error_to_types_error("the bucket folder allowlist is not valid UTF-8")
150 })?;
151 map = map.with_key_value("bucket_folder_allowlist", joined);
152 }
153 Ok(map)
154 }
155}
156
157fn std_error_to_types_error(error: impl std::fmt::Display) -> surrealdb_types::Error {
159 surrealdb_types::Error::internal(error.to_string())
160}
161
162#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
168fn spawn<F>(future: F)
169where
170 F: Future<Output = ()> + Send + 'static,
171{
172 drop(tokio::spawn(future));
173}
174
175#[cfg(all(target_family = "wasm", target_os = "unknown"))]
176fn spawn<F>(future: F)
177where
178 F: Future<Output = ()> + 'static,
179{
180 wasm_bindgen_futures::spawn_local(future);
181}
182
183pub async fn connect(
190 config: LocalConfig,
191 session_rx: Receiver<SessionId>,
192) -> Result<Arc<LocalEngine>, Error> {
193 let builder = Datastore::builder()
194 .with_config(config.datastore_config()?)
195 .with_engine_options(config.engine_options())
198 .with_query_timeout(config.query_timeout)
199 .with_transaction_timeout(config.transaction_timeout)
200 .with_auth(config.root.is_some());
201
202 #[cfg(storage)]
203 let builder = builder.with_temporary_directory(config.temporary_directory);
204
205 let (notifications, builder) = if config.capabilities.allows_live_query_notifications() {
206 let (send, recv) = async_channel::bounded(surrealdb_cnf::NOTIFICATIONS_CHANNEL_SIZE);
207 (Some(recv), builder.with_notify(send))
208 } else {
209 (None, builder)
210 };
211
212 let builder = builder.with_capabilities(config.capabilities);
213
214 let kvs = builder
220 .without_maintenance_tasks()
221 .build_with_path(&config.path)
222 .await
223 .map_err(std_error_to_types_error)?;
224 let started = async {
228 kvs.check_version().await.map_err(std_error_to_types_error)?;
229 kvs.bootstrap().await.map_err(std_error_to_types_error)?;
230 kvs.start_maintenance_tasks_checked().await.map_err(std_error_to_types_error)?;
231 if let Some(root) = &config.root {
235 if kvs.is_read_only() {
236 tracing::warn!(
237 "The datastore is open read-only, so the root credentials were not initialised"
238 );
239 } else {
240 kvs.initialise_credentials(&root.username, &root.password)
241 .await
242 .map_err(std_error_to_types_error)?;
243 }
244 }
245 Ok(())
246 }
247 .await;
248 if let Err(e) = started {
249 kvs.shutdown().await.ok();
250 return Err(e);
251 }
252
253 Ok(serve(kvs, notifications, session_rx))
254}
255
256pub fn from_datastore(
264 datastore: Arc<Datastore>,
265 notifications: Option<Receiver<Notification>>,
266 session_rx: Receiver<SessionId>,
267) -> Arc<LocalEngine> {
268 serve(datastore, notifications, session_rx)
269}
270
271fn serve(
275 kvs: Arc<Datastore>,
276 notifications: Option<Receiver<Notification>>,
277 session_rx: Receiver<SessionId>,
278) -> Arc<LocalEngine> {
279 let sessions = Arc::new(SessionRegistry::default());
280
281 let pump = notifications
286 .clone()
287 .map(|notifications| session::pump(Arc::clone(&kvs), Arc::clone(&sessions), notifications));
288 let run = session::run(Arc::clone(&kvs), Arc::clone(&sessions), session_rx, notifications);
289 let (stopped_tx, stopped) = async_channel::bounded::<Result<(), Error>>(1);
292 spawn(async move {
293 let outcome = match pump {
294 Some(pump) => futures::future::join(run, pump).await.0,
295 None => run.await,
296 };
297 stopped_tx.send(outcome).await.ok();
298 });
299
300 Arc::new(LocalEngine {
301 kvs,
302 sessions,
303 stopped,
304 })
305}
306
307#[cfg(all(test, not(target_family = "wasm")))]
308mod tests {
309 use surrealdb_kvs_surrealkv::SurrealKvConfig;
310
311 use super::LocalConfig;
312
313 fn options(pairs: &[(&str, &str)]) -> LocalConfig {
314 LocalConfig {
315 datastore_options: pairs.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect(),
316 ..LocalConfig::default()
317 }
318 }
319
320 #[test]
323 fn datastore_options_reach_the_backend_config() {
324 let config = options(&[
325 ("surrealkv_block_cache_capacity", "268435456"),
326 ("SURREALKV_MAX_MEMTABLE_SIZE", "67108864"),
327 ]);
328 let engine = config.datastore_config().unwrap().load::<SurrealKvConfig>();
329 assert_eq!(engine.block_cache_capacity, 256 * 1024 * 1024);
330 assert_eq!(engine.max_memtable_size, 64 * 1024 * 1024);
331 }
332
333 #[test]
335 fn unset_datastore_options_keep_the_backend_defaults() {
336 let engine = LocalConfig::default().datastore_config().unwrap().load::<SurrealKvConfig>();
337 let defaults = SurrealKvConfig::default();
338 assert_eq!(engine.block_cache_capacity, defaults.block_cache_capacity);
339 assert_eq!(engine.max_memtable_size, defaults.max_memtable_size);
340 }
341
342 #[test]
344 fn bucket_folder_allowlist_is_refused_as_a_datastore_option() {
345 for key in ["bucket_folder_allowlist", "BUCKET_FOLDER_ALLOWLIST"] {
346 assert!(options(&[(key, "/")]).datastore_config().is_err(), "{key}");
347 }
348 }
349}