1use 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#[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 <&serde_json::value::RawValue>::deserialize(deserializer).map(Some)
121}
122
123#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
125pub struct Bookmark {
126 pub term: u64,
127 pub index: u64,
128}
129
130#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize)]
132#[serde(rename_all = "UPPERCASE")]
133pub enum CommitAcknowledgement {
134 #[default]
135 Published,
136}
137
138#[derive(Clone, Debug, Serialize)]
140pub struct Query {
141 pub cypher: String,
142 pub parameters: BTreeMap<String, Value>,
143 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#[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#[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#[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 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
610pub 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#[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
808pub 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}