Skip to main content

irongraph_sdk/
lib.rs

1//! IronGraph SDK for embedded databases and remote API/Bolt connections.
2//!
3//! Documents, vector search, graph algorithms, projects, and administration use the same
4//! [`Query`] interface. Synchronous methods block the caller; asynchronous embedded methods
5//! run native work on Tokio's blocking pool and cancel active operations when dropped.
6
7use serde::{Deserialize, Serialize};
8use serde_json::{Value, json};
9use std::{collections::BTreeMap, fmt, path::PathBuf};
10
11#[repr(C)]
12struct Buffer {
13    data: *mut u8,
14    len: usize,
15}
16unsafe extern "C" {
17    fn irongraph_abi_version() -> u32;
18    fn irongraph_package_version_v1() -> *const std::ffi::c_char;
19    fn irongraph_call_v1(request: *const u8, len: usize, out: *mut Buffer) -> i32;
20    fn irongraph_buffer_free_v1(buffer: Buffer);
21}
22
23/// Structured native or SDK error. Database error codes and retry information are preserved.
24#[derive(Clone, Debug, Deserialize, Serialize)]
25pub struct Error {
26    pub code: String,
27    pub message: String,
28    pub retryable: bool,
29    pub retry_after_ms: Option<u64>,
30}
31impl Error {
32    fn sdk(message: impl Into<String>) -> Self {
33        Self {
34            code: "SDK_PROTOCOL".into(),
35            message: message.into(),
36            retryable: false,
37            retry_after_ms: None,
38        }
39    }
40}
41impl fmt::Display for Error {
42    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
43        write!(formatter, "{}: {}", self.code, self.message)
44    }
45}
46impl std::error::Error for Error {}
47pub type Result<T> = std::result::Result<T, Error>;
48
49struct OwnedBuffer(Buffer);
50impl Drop for OwnedBuffer {
51    fn drop(&mut self) {
52        unsafe {
53            irongraph_buffer_free_v1(Buffer {
54                data: self.0.data,
55                len: self.0.len,
56            });
57        }
58    }
59}
60
61fn call(request: Value) -> Result<Value> {
62    call_typed(request)
63}
64
65fn call_typed<T: serde::de::DeserializeOwned>(request: Value) -> Result<T> {
66    if unsafe { irongraph_abi_version() } != 1 {
67        return Err(Error::sdk("native library ABI version mismatch"));
68    }
69    let version = unsafe { std::ffi::CStr::from_ptr(irongraph_package_version_v1()) };
70    if version.to_bytes() != env!("CARGO_PKG_VERSION").as_bytes() {
71        return Err(Error::sdk("native library package version mismatch"));
72    }
73    let bytes = serde_json::to_vec(&request).map_err(|error| Error::sdk(error.to_string()))?;
74    let mut buffer = Buffer {
75        data: std::ptr::null_mut(),
76        len: 0,
77    };
78    let status = unsafe { irongraph_call_v1(bytes.as_ptr(), bytes.len(), &mut buffer) };
79    if status == 2 {
80        return Err(Error::sdk("native library rejected request buffer"));
81    }
82    let buffer = OwnedBuffer(buffer);
83    if buffer.0.data.is_null() || buffer.0.len > isize::MAX as usize {
84        return Err(Error::sdk("native library returned an invalid buffer"));
85    }
86    let bytes = unsafe { std::slice::from_raw_parts(buffer.0.data, buffer.0.len) };
87    let response: NativeResponse<'_> =
88        serde_json::from_slice(bytes).map_err(|error| Error::sdk(error.to_string()))?;
89    if response.version != env!("CARGO_PKG_VERSION") {
90        return Err(Error::sdk("native library package version mismatch"));
91    }
92    match (status, response.ok) {
93        (0, true) => serde_json::from_str(
94            response
95                .result
96                .ok_or_else(|| Error::sdk("native result is missing"))?
97                .get(),
98        )
99        .map_err(|error| Error::sdk(error.to_string())),
100        (1, false) => Err(response
101            .error
102            .ok_or_else(|| Error::sdk("native error is missing"))?),
103        _ => Err(Error::sdk("native response status is inconsistent")),
104    }
105}
106
107#[derive(Deserialize)]
108struct NativeResponse<'a> {
109    ok: bool,
110    version: &'a str,
111    #[serde(default, borrow, deserialize_with = "present_native_result")]
112    result: Option<&'a serde_json::value::RawValue>,
113    error: Option<Error>,
114}
115
116fn present_native_result<'de, D: serde::Deserializer<'de>>(
117    deserializer: D,
118) -> std::result::Result<Option<&'de serde_json::value::RawValue>, D::Error> {
119    // Preserve an explicitly returned null, and distinguish it from a missing result field.
120    <&serde_json::value::RawValue>::deserialize(deserializer).map(Some)
121}
122
123/// Position of an applied database write.
124#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
125pub struct Bookmark {
126    pub term: u64,
127    pub index: u64,
128}
129
130/// Acknowledgement for a write applied by this single-node database.
131#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize)]
132#[serde(rename_all = "UPPERCASE")]
133pub enum CommitAcknowledgement {
134    #[default]
135    Published,
136}
137
138/// One Cypher request covering the complete database query and administration surface.
139#[derive(Clone, Debug, Serialize)]
140pub struct Query {
141    pub cypher: String,
142    pub parameters: BTreeMap<String, Value>,
143    /// Immutable project UUID, returned by `SHOW PROJECTS`; no default project is assumed.
144    pub project_id: Option<String>,
145    pub bookmark: Option<Bookmark>,
146    pub consistency: CommitAcknowledgement,
147}
148impl Query {
149    pub fn new(cypher: impl Into<String>) -> Self {
150        Self {
151            cypher: cypher.into(),
152            parameters: BTreeMap::new(),
153            project_id: None,
154            bookmark: None,
155            consistency: CommitAcknowledgement::Published,
156        }
157    }
158    pub fn with_project(mut self, project_id: impl Into<String>) -> Self {
159        self.project_id = Some(project_id.into());
160        self
161    }
162    pub fn with_parameter(mut self, name: impl Into<String>, value: impl Into<Value>) -> Self {
163        self.parameters.insert(name.into(), value.into());
164        self
165    }
166    pub fn with_bookmark(mut self, bookmark: Bookmark) -> Self {
167        self.bookmark = Some(bookmark);
168        self
169    }
170}
171
172/// Lossless Query API result. Values retain their protocol type tags; 64-bit graph integers
173/// remain decimal strings, and nodes, relationships, paths, vectors, and temporal values retain
174/// their complete structure. Inspect `rows[row][column]` with `serde_json`.
175#[derive(Clone, Debug, Deserialize, Serialize)]
176pub struct QueryResult {
177    pub catalog: Option<Value>,
178    pub columns: Vec<Value>,
179    pub rows: Vec<Vec<Value>>,
180    pub summary: Value,
181}
182
183#[derive(Clone, Copy, Debug, Default)]
184pub enum ExecutionDevice {
185    #[default]
186    Auto,
187    Cpu,
188    Metal(u32),
189    Cuda(u32),
190}
191/// Independently selected text inference device.
192#[derive(Clone, Copy, Debug, Default)]
193pub enum EmbeddingDevice {
194    #[default]
195    Auto,
196    Cpu,
197    Metal(u32),
198    Cuda(u32),
199}
200#[derive(Clone, Copy, Debug, Default, Serialize)]
201#[serde(rename_all = "snake_case")]
202pub enum EmbeddingPolicy {
203    #[default]
204    Automatic,
205    Disabled,
206}
207
208/// Options for one database process. Automatic embeddings install and warm the local model.
209#[derive(Clone, Debug)]
210pub struct EmbeddedOptions {
211    pub data_dir: PathBuf,
212    pub model_dir: Option<PathBuf>,
213    pub embedding_cache_dir: Option<PathBuf>,
214    pub execution_device: ExecutionDevice,
215    pub embedding_device: EmbeddingDevice,
216    pub embedding_policy: EmbeddingPolicy,
217    pub worker_threads: Option<usize>,
218}
219impl EmbeddedOptions {
220    pub fn new(data_dir: impl Into<PathBuf>) -> Self {
221        Self {
222            data_dir: data_dir.into(),
223            model_dir: None,
224            embedding_cache_dir: None,
225            execution_device: ExecutionDevice::Auto,
226            embedding_device: EmbeddingDevice::Auto,
227            embedding_policy: EmbeddingPolicy::Automatic,
228            worker_threads: None,
229        }
230    }
231    pub fn with_execution_device(mut self, device: ExecutionDevice) -> Self {
232        self.execution_device = device;
233        self
234    }
235    pub fn with_embedding_policy(mut self, policy: EmbeddingPolicy) -> Self {
236        self.embedding_policy = policy;
237        self
238    }
239    pub fn with_embedding_device(mut self, device: EmbeddingDevice) -> Self {
240        self.embedding_device = device;
241        self
242    }
243    pub fn with_model_dir(mut self, directory: impl Into<PathBuf>) -> Self {
244        self.model_dir = Some(directory.into());
245        self
246    }
247    pub fn with_embedding_cache_dir(mut self, directory: impl Into<PathBuf>) -> Self {
248        self.embedding_cache_dir = Some(directory.into());
249        self
250    }
251    fn json(self) -> Value {
252        let (device, ordinal) = match self.execution_device {
253            ExecutionDevice::Auto => ("auto", 0),
254            ExecutionDevice::Cpu => ("cpu", 0),
255            ExecutionDevice::Metal(ordinal) => ("metal", ordinal),
256            ExecutionDevice::Cuda(ordinal) => ("cuda", ordinal),
257        };
258        let (embedding_device, embedding_ordinal) = match self.embedding_device {
259            EmbeddingDevice::Auto => ("auto", 0),
260            EmbeddingDevice::Cpu => ("cpu", 0),
261            EmbeddingDevice::Metal(ordinal) => ("metal", ordinal),
262            EmbeddingDevice::Cuda(ordinal) => ("cuda", ordinal),
263        };
264        json!({"data_dir":self.data_dir,"model_dir":self.model_dir,"embedding_cache_dir":self.embedding_cache_dir,"execution_device":device,"device_ordinal":ordinal,"embedding_policy":self.embedding_policy,
265            "embedding_device":embedding_device,"embedding_device_ordinal":embedding_ordinal,
266            "worker_threads":self.worker_threads})
267    }
268}
269
270struct Handle(Option<u64>, Option<tokio::sync::OwnedSemaphorePermit>);
271
272#[cfg(test)]
273mod application_paths_tests {
274    use super::*;
275
276    #[test]
277    fn application_paths_serialize_independent_storage_options() {
278        let options = EmbeddedOptions::new("app/data")
279            .with_model_dir("app/models")
280            .with_embedding_cache_dir("app/cache")
281            .json();
282        assert_eq!(options["data_dir"], "app/data");
283        assert_eq!(options["model_dir"], "app/models");
284        assert_eq!(options["embedding_cache_dir"], "app/cache");
285        let defaults = EmbeddedOptions::new("app/data").json();
286        assert!(defaults["model_dir"].is_null());
287        assert!(defaults["embedding_cache_dir"].is_null());
288    }
289}
290
291struct HandleTeardown {
292    handle: u64,
293    _permit: tokio::sync::OwnedSemaphorePermit,
294}
295struct HandleReaper {
296    sender: std::sync::mpsc::SyncSender<HandleTeardown>,
297    permits: std::sync::Arc<tokio::sync::Semaphore>,
298    failed: std::sync::atomic::AtomicBool,
299}
300static HANDLE_REAPER: std::sync::OnceLock<std::result::Result<HandleReaper, String>> =
301    std::sync::OnceLock::new();
302#[cfg(test)]
303type HandleTeardownGate = (std::sync::mpsc::Sender<()>, std::sync::mpsc::Receiver<()>);
304#[cfg(test)]
305static HANDLE_TEARDOWN_GATE: std::sync::Mutex<Option<HandleTeardownGate>> =
306    std::sync::Mutex::new(None);
307
308fn handle_reaper() -> Result<&'static HandleReaper> {
309    let reaper = HANDLE_REAPER
310        .get_or_init(|| {
311            let (sender, receiver) = std::sync::mpsc::sync_channel::<HandleTeardown>(64);
312            std::thread::Builder::new()
313                .name("irongraph-sdk-teardown".into())
314                .spawn(move || {
315                    for teardown in receiver {
316                        #[cfg(test)]
317                        if let Some((entered, release)) =
318                            HANDLE_TEARDOWN_GATE.lock().unwrap().take()
319                        {
320                            let _ = entered.send(());
321                            let _ = release.recv();
322                        }
323                        let _ = std::panic::catch_unwind(|| {
324                            let _ = call(json!({"action":"close","handle":teardown.handle}));
325                        });
326                        drop(teardown);
327                    }
328                })
329                .map_err(|error| error.to_string())?;
330            Ok(HandleReaper {
331                sender,
332                permits: std::sync::Arc::new(tokio::sync::Semaphore::new(64)),
333                failed: std::sync::atomic::AtomicBool::new(false),
334            })
335        })
336        .as_ref()
337        .map_err(|error| Error::sdk(format!("SDK teardown worker failed: {error}")))?;
338    if reaper.failed.load(std::sync::atomic::Ordering::Acquire) {
339        return Err(Error::sdk("SDK teardown worker is unavailable"));
340    }
341    Ok(reaper)
342}
343#[cfg(test)]
344mod embedding_configuration_tests {
345    use super::*;
346
347    #[test]
348    fn native_envelope_borrows_result_and_distinguishes_null_from_missing() {
349        let null: NativeResponse<'_> =
350            serde_json::from_str(r#"{"ok":true,"version":"0.1.6","result":null}"#).unwrap();
351        assert_eq!(null.result.unwrap().get(), "null");
352        let missing: NativeResponse<'_> =
353            serde_json::from_str(r#"{"ok":true,"version":"0.1.6"}"#).unwrap();
354        assert!(missing.result.is_none());
355        let dirty = serde_json::json!({"rows":[[{"type":"string","value":"Unicode 🦀\\\"\0".repeat(16_384)}]],"columns":[],"catalog":null,"summary":{}});
356        let encoded = serde_json::json!({"ok":true,"version":"0.1.6","result":dirty}).to_string();
357        let response: NativeResponse<'_> = serde_json::from_str(&encoded).unwrap();
358        let raw = response.result.unwrap().get();
359        assert!(raw.as_ptr() >= encoded.as_ptr());
360        assert!(raw.as_bytes().as_ptr_range().end <= encoded.as_bytes().as_ptr_range().end);
361        let result: QueryResult = serde_json::from_str(raw).unwrap();
362        assert_eq!(serde_json::to_value(result).unwrap(), dirty);
363    }
364
365    #[test]
366    fn cpu_graph_serializes_independent_embedding_device() {
367        let options = EmbeddedOptions::new("test-data")
368            .with_execution_device(ExecutionDevice::Cpu)
369            .with_embedding_device(EmbeddingDevice::Metal(2))
370            .json();
371        assert_eq!(options["execution_device"], "cpu");
372        assert_eq!(options["embedding_device"], "metal");
373        assert_eq!(options["embedding_device_ordinal"], 2);
374        assert_eq!(
375            EmbeddedOptions::new("test-data").json()["embedding_device"],
376            "auto"
377        );
378    }
379}
380impl Handle {
381    fn open(request: Value) -> Result<Self> {
382        let permit = handle_reaper()?
383            .permits
384            .clone()
385            .try_acquire_owned()
386            .map_err(|_| Error {
387                code: "BACKPRESSURE".into(),
388                message: "SDK native handle capacity exhausted before open".into(),
389                retryable: true,
390                retry_after_ms: None,
391            })?;
392        call(request)?["handle"]
393            .as_u64()
394            .filter(|handle| *handle != 0)
395            .map(|handle| Self(Some(handle), Some(permit)))
396            .ok_or_else(|| Error::sdk("native open returned an invalid handle"))
397    }
398    fn query(&self, query: Query) -> Result<QueryResult> {
399        call_typed(json!({"action":"query","handle":self.0,"query":query}))
400    }
401    fn close(&mut self) -> Result<()> {
402        if let Some(handle) = self.0.take() {
403            let result = call(json!({"action":"close","handle":handle}));
404            self.1.take();
405            result?;
406        }
407        Ok(())
408    }
409}
410impl Drop for Handle {
411    fn drop(&mut self) {
412        if let Some(handle) = self.0.take() {
413            let teardown = HandleTeardown {
414                handle,
415                _permit: self
416                    .1
417                    .take()
418                    .expect("live handle retains lifecycle admission"),
419            };
420            let reaper = HANDLE_REAPER
421                .get()
422                .expect("open initialized reaper")
423                .as_ref()
424                .expect("open admitted reaper");
425            if let Err(error) = reaper.sender.try_send(teardown) {
426                reaper
427                    .failed
428                    .store(true, std::sync::atomic::Ordering::Release);
429                let (std::sync::mpsc::TrySendError::Full(teardown)
430                | std::sync::mpsc::TrySendError::Disconnected(teardown)) = error;
431                std::mem::forget(teardown);
432            }
433        }
434    }
435}
436
437#[cfg(test)]
438mod bounded_teardown_tests {
439    use super::*;
440
441    #[test]
442    fn paused_native_teardown_bounds_handles_and_keeps_current_thread_responsive() {
443        let directory = tempfile::tempdir().unwrap();
444        let options =
445            EmbeddedOptions::new(directory.path()).with_embedding_policy(EmbeddingPolicy::Disabled);
446        let database = EmbeddedDatabase::open(options.clone()).unwrap();
447        let (entered, observed) = std::sync::mpsc::channel();
448        let (release, blocked) = std::sync::mpsc::channel();
449        *HANDLE_TEARDOWN_GATE.lock().unwrap() = Some((entered, blocked));
450        let runtime = tokio::runtime::Builder::new_current_thread()
451            .enable_all()
452            .build()
453            .unwrap();
454        runtime.block_on(async {
455            drop(database);
456            tokio::time::sleep(std::time::Duration::from_millis(1)).await;
457        });
458        observed
459            .recv_timeout(std::time::Duration::from_secs(5))
460            .unwrap();
461        let mut handles = Vec::new();
462        for _ in 0..63 {
463            handles.push(RemoteClient::api("http://127.0.0.1:1").unwrap());
464        }
465        let error = match RemoteClient::api("http://127.0.0.1:1") {
466            Err(error) => error,
467            Ok(_) => panic!("teardown did not retain handle admission"),
468        };
469        assert_eq!(error.code, "BACKPRESSURE");
470        for handle in handles {
471            handle.close().unwrap();
472        }
473        assert!(
474            EmbeddedDatabase::open(options.clone()).is_err(),
475            "instance guard released before actual teardown"
476        );
477        release.send(()).unwrap();
478        runtime.block_on(async {
479            tokio::time::timeout(std::time::Duration::from_secs(5), async {
480                while handle_reaper().unwrap().permits.available_permits() != 64 {
481                    tokio::time::sleep(std::time::Duration::from_millis(1)).await;
482                }
483            })
484            .await
485            .unwrap();
486        });
487        EmbeddedDatabase::open(options.clone())
488            .unwrap()
489            .close()
490            .unwrap();
491        EmbeddedDatabase::open(options).unwrap().close().unwrap();
492    }
493}
494
495static ASYNC_JOBS: std::sync::LazyLock<std::sync::Arc<tokio::sync::Semaphore>> =
496    std::sync::LazyLock::new(|| std::sync::Arc::new(tokio::sync::Semaphore::new(64)));
497static ASYNC_CONTROLS: std::sync::LazyLock<std::sync::Arc<tokio::sync::Semaphore>> =
498    std::sync::LazyLock::new(|| std::sync::Arc::new(tokio::sync::Semaphore::new(64)));
499static ASYNC_CANCELLATIONS: std::sync::LazyLock<std::sync::Arc<tokio::sync::Semaphore>> =
500    std::sync::LazyLock::new(|| std::sync::Arc::new(tokio::sync::Semaphore::new(64)));
501static ASYNC_OPERATION_ID: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
502
503struct AsyncCancellation {
504    operation: Option<(u64, String)>,
505    cancelled: std::sync::Arc<std::sync::atomic::AtomicBool>,
506    abort: tokio::task::AbortHandle,
507    runtime: tokio::runtime::Handle,
508    control: Option<tokio::sync::OwnedSemaphorePermit>,
509    job: std::sync::Arc<tokio::sync::OwnedSemaphorePermit>,
510}
511impl Drop for AsyncCancellation {
512    fn drop(&mut self) {
513        let Some((handle, operation_id)) = self.operation.take() else {
514            return;
515        };
516        if self.abort.is_finished() {
517            return;
518        }
519        self.cancelled
520            .store(true, std::sync::atomic::Ordering::Release);
521        // Blocking tasks can only be aborted before they start. A running native request
522        // may still be parsing its packet, so retry until registration or completion.
523        self.abort.abort();
524        let abort = self.abort.clone();
525        let control = self.control.take();
526        let job = self.job.clone();
527        self.runtime.spawn_blocking(move || {
528            let _control = control;
529            let _job = job;
530            while !abort.is_finished() {
531                match call(json!({"action":"cancel","handle":handle,"operation_id":operation_id})) {
532                    Ok(result) if result.as_bool() == Some(true) => break,
533                    Err(_) => break,
534                    _ => std::thread::sleep(std::time::Duration::from_millis(1)),
535                }
536            }
537        });
538    }
539}
540async fn blocking<T: Send + 'static>(
541    operation: Option<(u64, String)>,
542    bounded: bool,
543    work: impl FnOnce() -> Result<T> + Send + 'static,
544) -> Result<T> {
545    let runtime = tokio::runtime::Handle::try_current()
546        .map_err(|_| Error::sdk("asynchronous embedded calls require a Tokio runtime"))?;
547    let admission = if bounded {
548        &*ASYNC_JOBS
549    } else {
550        &*ASYNC_CONTROLS
551    };
552    let permit = admission
553        .clone()
554        .acquire_owned()
555        .await
556        .map_err(|_| Error::sdk("asynchronous SDK workers are closed"))?;
557    let control = if operation.is_some() {
558        Some(
559            ASYNC_CANCELLATIONS
560                .clone()
561                .acquire_owned()
562                .await
563                .map_err(|_| Error::sdk("asynchronous SDK cancellation workers are closed"))?,
564        )
565    } else {
566        None
567    };
568    let permit = std::sync::Arc::new(permit);
569    let worker_permit = permit.clone();
570    let cancelled = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
571    let worker_cancelled = cancelled.clone();
572    let task = runtime.spawn_blocking(move || {
573        let _permit = worker_permit;
574        if worker_cancelled.load(std::sync::atomic::Ordering::Acquire) {
575            return Err(Error::sdk(
576                "asynchronous operation cancelled before dispatch",
577            ));
578        }
579        work()
580    });
581    let mut cancellation = AsyncCancellation {
582        operation,
583        control,
584        job: permit,
585        cancelled,
586        abort: task.abort_handle(),
587        runtime,
588    };
589    let result = task.await;
590    cancellation.operation = None;
591    result.map_err(|error| Error::sdk(format!("native worker failed: {error}")))?
592}
593fn async_options(mut options: OperationOptions) -> (OperationOptions, String) {
594    let id = options
595        .operation_id
596        .get_or_insert_with(|| {
597            format!(
598                "sdk:{}:{}",
599                std::process::id(),
600                ASYNC_OPERATION_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
601            )
602        })
603        .clone();
604    (options, id)
605}
606fn decode<T: serde::de::DeserializeOwned>(request: Value) -> Result<T> {
607    call_typed(request)
608}
609
610/// Database with synchronous and Tokio asynchronous access to the same native owner.
611/// Only one embedded instance can be active in a process. Close explicitly to observe shutdown errors.
612pub struct EmbeddedDatabase(Handle);
613
614#[derive(Clone, Debug, Default, Serialize, Deserialize)]
615pub struct OperationOptions {
616    pub operation_id: Option<String>,
617    pub timeout_ms: Option<u64>,
618}
619
620#[derive(Clone, Debug, Serialize, Deserialize)]
621pub struct StreamRecord {
622    pub key: Option<Vec<u8>>,
623    pub headers: BTreeMap<String, Vec<u8>>,
624    pub value: Option<Vec<u8>>,
625    pub create_time_ms: Option<i64>,
626}
627
628#[derive(Clone, Debug, Serialize, Deserialize)]
629pub struct StreamAppend {
630    pub project_id: String,
631    pub topic: String,
632    pub partition: i32,
633    pub records: Vec<StreamRecord>,
634}
635
636#[derive(Clone, Debug, Serialize, Deserialize)]
637pub struct StreamAcknowledgement {
638    pub bookmark: Bookmark,
639    pub first_offset: u64,
640    pub record_count: u32,
641}
642
643#[derive(Clone, Debug, Serialize, Deserialize)]
644pub struct StreamFetch {
645    pub project_id: String,
646    pub topic: String,
647    pub partition: i32,
648    pub offset: u64,
649    pub max_records: usize,
650    pub max_bytes: usize,
651}
652
653#[derive(Clone, Debug, Serialize, Deserialize)]
654pub struct StreamPayload {
655    pub id: u64,
656    pub resolved_time_ms: i64,
657    pub ingress: Value,
658    pub payload: Vec<u8>,
659    pub checksum: Vec<u8>,
660}
661
662#[derive(Clone, Debug, Serialize, Deserialize)]
663pub struct StreamPage {
664    pub records: Vec<(u64, StreamPayload)>,
665    pub high_watermark: u64,
666    pub next_offset: u64,
667    pub truncated: bool,
668}
669
670#[derive(Clone, Debug, Serialize, Deserialize)]
671pub struct RuntimeStatus {
672    pub data_dir: PathBuf,
673    pub ready: bool,
674    pub active_operations: usize,
675    pub worker_threads: usize,
676}
677
678impl EmbeddedDatabase {
679    pub async fn open_async(options: EmbeddedOptions) -> Result<Self> {
680        blocking(None, true, move || Self::open(options)).await
681    }
682    pub async fn query_async(&self, query: Query) -> Result<QueryResult> {
683        self.query_with_options_async(query, OperationOptions::default())
684            .await
685    }
686    pub async fn query_with_options_async(
687        &self,
688        query: Query,
689        options: OperationOptions,
690    ) -> Result<QueryResult> {
691        let handle = self.0.0.ok_or_else(|| Error::sdk("database is closed"))?;
692        let (options, id) = async_options(options);
693        blocking(Some((handle, id)), true, move || {
694            decode(json!({"action":"query","handle":handle,"query":query,"options":options}))
695        })
696        .await
697    }
698    pub async fn stream_append_async(
699        &self,
700        request: StreamAppend,
701        options: OperationOptions,
702    ) -> Result<StreamAcknowledgement> {
703        let handle = self.0.0.ok_or_else(|| Error::sdk("database is closed"))?;
704        let (options, id) = async_options(options);
705        blocking(Some((handle, id)), true, move || decode(json!({"action":"stream_append","handle":handle,"request":request,"options":options}))).await
706    }
707    pub async fn stream_fetch_async(
708        &self,
709        request: StreamFetch,
710        options: OperationOptions,
711    ) -> Result<StreamPage> {
712        let handle = self.0.0.ok_or_else(|| Error::sdk("database is closed"))?;
713        let (options, id) = async_options(options);
714        blocking(Some((handle, id)), true, move || decode(json!({"action":"stream_fetch","handle":handle,"request":request,"options":options}))).await
715    }
716    pub async fn status_async(&self) -> Result<RuntimeStatus> {
717        let handle = self.0.0;
718        blocking(None, false, move || {
719            decode(json!({"action":"status","handle":handle}))
720        })
721        .await
722    }
723    pub async fn cancel_async(&self, operation_id: &str) -> Result<bool> {
724        let handle = self.0.0;
725        let operation_id = operation_id.to_owned();
726        blocking(None, false, move || {
727            decode(json!({"action":"cancel","handle":handle,"operation_id":operation_id}))
728        })
729        .await
730    }
731    pub async fn flush_async(&self) -> Result<()> {
732        let handle = self.0.0;
733        blocking(None, true, move || {
734            call(json!({"action":"flush","handle":handle})).map(|_| ())
735        })
736        .await
737    }
738    pub async fn close_async(self) -> Result<()> {
739        blocking(None, false, move || self.close()).await
740    }
741    pub fn open(options: EmbeddedOptions) -> Result<Self> {
742        Handle::open(json!({"action":"open_embedded","options":options.json()})).map(Self)
743    }
744    pub fn query(&self, query: Query) -> Result<QueryResult> {
745        self.0.query(query)
746    }
747    pub fn query_with_options(
748        &self,
749        query: Query,
750        options: OperationOptions,
751    ) -> Result<QueryResult> {
752        call_typed(json!({"action":"query","handle":self.0.0,"query":query,"options":options}))
753    }
754    pub fn stream_append(
755        &self,
756        request: StreamAppend,
757        options: OperationOptions,
758    ) -> Result<StreamAcknowledgement> {
759        call_typed(
760            json!({"action":"stream_append","handle":self.0.0,"request":request,"options":options}),
761        )
762    }
763    pub fn stream_fetch(
764        &self,
765        request: StreamFetch,
766        options: OperationOptions,
767    ) -> Result<StreamPage> {
768        call_typed(
769            json!({"action":"stream_fetch","handle":self.0.0,"request":request,"options":options}),
770        )
771    }
772    pub fn status(&self) -> Result<RuntimeStatus> {
773        call_typed(json!({"action":"status","handle":self.0.0}))
774    }
775    pub fn cancel(&self, operation_id: &str) -> Result<bool> {
776        call_typed(json!({"action":"cancel","handle":self.0.0,"operation_id":operation_id}))
777    }
778    pub fn flush(&self) -> Result<()> {
779        call(json!({"action":"flush","handle":self.0.0}))?;
780        Ok(())
781    }
782    pub fn close(mut self) -> Result<()> {
783        self.0.close()
784    }
785}
786
787/// PEM paths for mutual TLS. Credentials are kept outside graph data.
788#[derive(Clone, Debug, Serialize)]
789pub struct MutualTls {
790    pub certificate: PathBuf,
791    pub private_key: PathBuf,
792    pub certificate_authority: PathBuf,
793}
794impl MutualTls {
795    pub fn new(
796        certificate: impl Into<PathBuf>,
797        private_key: impl Into<PathBuf>,
798        certificate_authority: impl Into<PathBuf>,
799    ) -> Self {
800        Self {
801            certificate: certificate.into(),
802            private_key: private_key.into(),
803            certificate_authority: certificate_authority.into(),
804        }
805    }
806}
807
808/// Remote Query API or Bolt connection. Plain connections are restricted to loopback addresses;
809/// remote connections require mutual TLS. Bolt requests require `Query::with_project`.
810pub struct RemoteClient(Handle);
811impl RemoteClient {
812    fn connect(transport: &str, endpoint: &str, tls: Option<&MutualTls>) -> Result<Self> {
813        Handle::open(json!({"action":"open_remote","options":{"transport":transport,"endpoint":endpoint,"tls":tls}})).map(Self)
814    }
815    pub fn api(endpoint: &str) -> Result<Self> {
816        Self::connect("api", endpoint, None)
817    }
818    pub fn bolt(endpoint: &str) -> Result<Self> {
819        Self::connect("bolt", endpoint, None)
820    }
821    pub fn api_mtls(endpoint: &str, tls: &MutualTls) -> Result<Self> {
822        Self::connect("api", endpoint, Some(tls))
823    }
824    pub fn bolt_mtls(endpoint: &str, tls: &MutualTls) -> Result<Self> {
825        Self::connect("bolt", endpoint, Some(tls))
826    }
827    pub fn query(&self, query: Query) -> Result<QueryResult> {
828        self.0.query(query)
829    }
830    pub fn close(mut self) -> Result<()> {
831        self.0.close()
832    }
833}