slatedb 0.1.0

data/ext/slatedb/src/iterator.rs

@@ -0,0 +1,118 @@
+use std::sync::Arc;
+
+use magnus::prelude::*;
+use magnus::{method, Error, Ruby};
+use slatedb::DbIterator;
+use tokio::sync::Mutex;
+
+/// Result type for raw byte key-value pairs.
+type ByteKvResult = Result<Option<(Vec<u8>, Vec<u8>)>, Error>;
+
+use crate::errors::{internal_error, invalid_argument_error, map_error};
+use crate::runtime::block_on;
+
+/// Ruby wrapper for SlateDB iterator.
+///
+/// This struct is exposed to Ruby as `SlateDb::Iterator`.
+/// It includes Enumerable support via the `each` method implemented in Ruby.
+#[magnus::wrap(class = "SlateDb::Iterator", free_immediately, size)]
+pub struct Iterator {
+    inner: Arc<Mutex<Option<DbIterator>>>,
+}
+
+impl Iterator {
+    /// Create a new Iterator from a DbIterator.
+    pub fn new(iter: DbIterator) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Some(iter))),
+        }
+    }
+
+    /// Get the next key-value pair.
+    ///
+    /// Returns [key, value] as an array, or nil if iteration is complete.
+    pub fn next_entry(&self) -> Result<Option<(String, String)>, Error> {
+        let inner = self.inner.clone();
+
+        let result = block_on(async {
+            let mut guard = inner.lock().await;
+            let iter = guard
+                .as_mut()
+                .ok_or_else(|| internal_error("iterator has been closed"))?;
+
+            iter.next().await.map_err(map_error)
+        })?;
+
+        Ok(result.map(|kv| {
+            (
+                String::from_utf8_lossy(&kv.key).to_string(),
+                String::from_utf8_lossy(&kv.value).to_string(),
+            )
+        }))
+    }
+
+    /// Get the next key-value pair as raw bytes.
+    ///
+    /// Returns [key, value] as byte arrays, or nil if iteration is complete.
+    pub fn next_entry_bytes(&self) -> ByteKvResult {
+        let inner = self.inner.clone();
+
+        let result = block_on(async {
+            let mut guard = inner.lock().await;
+            let iter = guard
+                .as_mut()
+                .ok_or_else(|| internal_error("iterator has been closed"))?;
+
+            iter.next().await.map_err(map_error)
+        })?;
+
+        Ok(result.map(|kv| (kv.key.to_vec(), kv.value.to_vec())))
+    }
+
+    /// Seek to a specific key position.
+    ///
+    /// After seeking, `next` will return entries starting from the given key.
+    pub fn seek(&self, key: String) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let inner = self.inner.clone();
+
+        block_on(async {
+            let mut guard = inner.lock().await;
+            let iter = guard
+                .as_mut()
+                .ok_or_else(|| internal_error("iterator has been closed"))?;
+
+            iter.seek(key.as_bytes()).await.map_err(map_error)
+        })?;
+
+        Ok(())
+    }
+
+    /// Close the iterator and release resources.
+    pub fn close(&self) -> Result<(), Error> {
+        let inner = self.inner.clone();
+
+        block_on(async {
+            let mut guard = inner.lock().await;
+            *guard = None;
+        });
+
+        Ok(())
+    }
+}
+
+/// Define the Iterator class on the SlateDb module.
+pub fn define_iterator_class(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("Iterator", ruby.class_object())?;
+
+    // Instance methods
+    class.define_method("next_entry", method!(Iterator::next_entry, 0))?;
+    class.define_method("next_entry_bytes", method!(Iterator::next_entry_bytes, 0))?;
+    class.define_method("seek", method!(Iterator::seek, 1))?;
+    class.define_method("close", method!(Iterator::close, 0))?;
+
+    Ok(())
+}

data/ext/slatedb/src/lib.rs

@@ -0,0 +1,50 @@
+//! SlateDB Ruby bindings
+//!
+//! This crate provides Ruby bindings for SlateDB, a cloud-native embedded
+//! key-value store built on object storage.
+//!
+//! # Example
+//!
+//! ```ruby
+//! require 'slatedb'
+//!
+//! db = SlateDb::Database.open("/tmp/mydb")
+//! db.put("hello", "world")
+//! db.get("hello") # => "world"
+//! db.close
+//! ```
+
+use magnus::{Error, Ruby};
+
+mod admin;
+mod database;
+mod errors;
+mod iterator;
+mod reader;
+mod runtime;
+mod snapshot;
+mod transaction;
+mod utils;
+mod write_batch;
+
+/// Initialize the SlateDb Ruby module.
+///
+/// This is called automatically when the native extension is loaded.
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("SlateDb")?;
+
+    // Define exception classes first
+    errors::define_exceptions(ruby, &module)?;
+
+    // Define core classes
+    database::define_database_class(ruby, &module)?;
+    iterator::define_iterator_class(ruby, &module)?;
+    write_batch::define_write_batch_class(ruby, &module)?;
+    transaction::define_transaction_class(ruby, &module)?;
+    snapshot::define_snapshot_class(ruby, &module)?;
+    reader::define_reader_class(ruby, &module)?;
+    admin::define_admin_class(ruby, &module)?;
+
+    Ok(())
+}

data/ext/slatedb/src/reader.rs

@@ -0,0 +1,233 @@
+use std::sync::Arc;
+
+use magnus::prelude::*;
+use magnus::{function, method, Error, RHash, Ruby};
+use slatedb::config::{DbReaderOptions, DurabilityLevel, ReadOptions, ScanOptions};
+use slatedb::DbReader;
+
+use crate::errors::{invalid_argument_error, map_error};
+use crate::iterator::Iterator;
+use crate::runtime::block_on;
+use crate::utils::get_optional;
+
+/// Ruby wrapper for SlateDB Reader.
+///
+/// This struct is exposed to Ruby as `SlateDb::Reader`.
+/// Provides read-only access to a database, optionally pinned to a checkpoint.
+#[magnus::wrap(class = "SlateDb::Reader", free_immediately, size)]
+pub struct Reader {
+    inner: Arc<DbReader>,
+}
+
+impl Reader {
+    /// Open a reader at the given path.
+    ///
+    /// # Arguments
+    /// * `path` - The path identifier for the database
+    /// * `url` - Optional object store URL
+    /// * `checkpoint_id` - Optional checkpoint UUID to read at
+    /// * `kwargs` - Additional options (manifest_poll_interval, checkpoint_lifetime, max_memtable_bytes)
+    pub fn open(
+        path: String,
+        url: Option<String>,
+        checkpoint_id: Option<String>,
+        kwargs: RHash,
+    ) -> Result<Self, Error> {
+        // Parse options
+        let manifest_poll_interval = get_optional::<u64>(&kwargs, "manifest_poll_interval")?
+            .map(std::time::Duration::from_millis);
+        let checkpoint_lifetime = get_optional::<u64>(&kwargs, "checkpoint_lifetime")?
+            .map(std::time::Duration::from_millis);
+        let max_memtable_bytes = get_optional::<u64>(&kwargs, "max_memtable_bytes")?;
+
+        // Parse checkpoint_id as UUID
+        let checkpoint_uuid =
+            if let Some(id_str) = checkpoint_id {
+                Some(uuid::Uuid::parse_str(&id_str).map_err(|e| {
+                    invalid_argument_error(&format!("invalid checkpoint_id: {}", e))
+                })?)
+            } else {
+                None
+            };
+
+        let reader = block_on(async {
+            let object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url) = url {
+                slatedb::Db::resolve_object_store(url).map_err(map_error)?
+            } else {
+                Arc::new(object_store::memory::InMemory::new())
+            };
+
+            let mut options = DbReaderOptions::default();
+            if let Some(interval) = manifest_poll_interval {
+                options.manifest_poll_interval = interval;
+            }
+            if let Some(lifetime) = checkpoint_lifetime {
+                options.checkpoint_lifetime = lifetime;
+            }
+            if let Some(max_bytes) = max_memtable_bytes {
+                options.max_memtable_bytes = max_bytes;
+            }
+
+            DbReader::open(path, object_store, checkpoint_uuid, options)
+                .await
+                .map_err(map_error)
+        })?;
+
+        Ok(Self {
+            inner: Arc::new(reader),
+        })
+    }
+
+    /// Get a value by key.
+    pub fn get(&self, key: String) -> Result<Option<String>, Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let result = block_on(async { self.inner.get(key.as_bytes()).await }).map_err(map_error)?;
+
+        Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
+    }
+
+    /// Get a value by key with options.
+    pub fn get_with_options(&self, key: String, kwargs: RHash) -> Result<Option<String>, Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let mut opts = ReadOptions::default();
+
+        if let Some(df) = get_optional::<String>(&kwargs, "durability_filter")? {
+            opts.durability_filter = match df.as_str() {
+                "remote" => DurabilityLevel::Remote,
+                "memory" => DurabilityLevel::Memory,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid durability_filter: {} (expected 'remote' or 'memory')",
+                        other
+                    )))
+                }
+            };
+        }
+
+        if let Some(dirty) = get_optional::<bool>(&kwargs, "dirty")? {
+            opts.dirty = dirty;
+        }
+
+        let result = block_on(async { self.inner.get_with_options(key.as_bytes(), &opts).await })
+            .map_err(map_error)?;
+
+        Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
+    }
+
+    /// Get a value by key as raw bytes.
+    pub fn get_bytes(&self, key: String) -> Result<Option<Vec<u8>>, Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let result = block_on(async { self.inner.get(key.as_bytes()).await }).map_err(map_error)?;
+
+        Ok(result.map(|b| b.to_vec()))
+    }
+
+    /// Scan a range of keys.
+    pub fn scan(&self, start: String, end_key: Option<String>) -> Result<Iterator, Error> {
+        if start.is_empty() {
+            return Err(invalid_argument_error("start key cannot be empty"));
+        }
+
+        let start_bytes = start.into_bytes();
+        let end_bytes = end_key.map(|e| e.into_bytes());
+
+        let iter = block_on(async {
+            let range = match end_bytes {
+                Some(end) => self.inner.scan(start_bytes..end).await,
+                None => self.inner.scan(start_bytes..).await,
+            };
+            range.map_err(map_error)
+        })?;
+
+        Ok(Iterator::new(iter))
+    }
+
+    /// Scan a range of keys with options.
+    pub fn scan_with_options(
+        &self,
+        start: String,
+        end_key: Option<String>,
+        kwargs: RHash,
+    ) -> Result<Iterator, Error> {
+        if start.is_empty() {
+            return Err(invalid_argument_error("start key cannot be empty"));
+        }
+
+        let mut opts = ScanOptions::default();
+
+        if let Some(df) = get_optional::<String>(&kwargs, "durability_filter")? {
+            opts.durability_filter = match df.as_str() {
+                "remote" => DurabilityLevel::Remote,
+                "memory" => DurabilityLevel::Memory,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid durability_filter: {} (expected 'remote' or 'memory')",
+                        other
+                    )))
+                }
+            };
+        }
+
+        if let Some(dirty) = get_optional::<bool>(&kwargs, "dirty")? {
+            opts.dirty = dirty;
+        }
+
+        if let Some(rab) = get_optional::<usize>(&kwargs, "read_ahead_bytes")? {
+            opts.read_ahead_bytes = rab;
+        }
+
+        if let Some(cb) = get_optional::<bool>(&kwargs, "cache_blocks")? {
+            opts.cache_blocks = cb;
+        }
+
+        if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
+            opts.max_fetch_tasks = mft;
+        }
+
+        let start_bytes = start.into_bytes();
+        let end_bytes = end_key.map(|e| e.into_bytes());
+
+        let iter = block_on(async {
+            let range = match end_bytes {
+                Some(end) => self.inner.scan_with_options(start_bytes..end, &opts).await,
+                None => self.inner.scan_with_options(start_bytes.., &opts).await,
+            };
+            range.map_err(map_error)
+        })?;
+
+        Ok(Iterator::new(iter))
+    }
+
+    /// Close the reader.
+    pub fn close(&self) -> Result<(), Error> {
+        block_on(async { self.inner.close().await }).map_err(map_error)?;
+        Ok(())
+    }
+}
+
+/// Define the Reader class on the SlateDb module.
+pub fn define_reader_class(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("Reader", ruby.class_object())?;
+
+    // Class methods
+    class.define_singleton_method("_open", function!(Reader::open, 4))?;
+
+    // Instance methods
+    class.define_method("_get", method!(Reader::get, 1))?;
+    class.define_method("_get_with_options", method!(Reader::get_with_options, 2))?;
+    class.define_method("get_bytes", method!(Reader::get_bytes, 1))?;
+    class.define_method("_scan", method!(Reader::scan, 2))?;
+    class.define_method("_scan_with_options", method!(Reader::scan_with_options, 3))?;
+    class.define_method("close", method!(Reader::close, 0))?;
+
+    Ok(())
+}

data/ext/slatedb/src/runtime.rs

@@ -0,0 +1,78 @@
+use once_cell::sync::OnceCell;
+use rb_sys::rb_thread_call_without_gvl;
+use std::ffi::c_void;
+use std::future::Future;
+use tokio::runtime::Runtime;
+
+static RUNTIME: OnceCell<Runtime> = OnceCell::new();
+
+/// Get or initialize the shared Tokio runtime for all SlateDB operations.
+///
+/// We use a multi-threaded runtime to support concurrent access from multiple
+/// Ruby threads. This is important for use with Sidekiq, Puma, and other
+/// multi-threaded Ruby applications.
+fn get_runtime() -> &'static Runtime {
+    RUNTIME.get_or_init(|| {
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .expect("Failed to create Tokio runtime")
+    })
+}
+
+/// Execute a future on the runtime, releasing the Ruby GVL while waiting.
+///
+/// This is critical for thread safety - it allows other Ruby threads to run
+/// while this thread waits for I/O operations to complete. Without this,
+/// multiple Ruby threads calling SlateDB operations would deadlock.
+pub fn block_on<F, T>(future: F) -> T
+where
+    F: Future<Output = T>,
+{
+    let rt = get_runtime();
+
+    // Use rb_thread_call_without_gvl to release the GVL while blocking
+    // This allows other Ruby threads to execute while we wait for I/O
+    without_gvl(|| rt.block_on(future))
+}
+
+/// Execute a closure without holding the Ruby GVL.
+///
+/// This releases the Global VM Lock, allowing other Ruby threads to run
+/// while this closure executes. Essential for I/O-bound operations.
+fn without_gvl<F, T>(f: F) -> T
+where
+    F: FnOnce() -> T,
+{
+    struct Closure<F, T> {
+        f: Option<F>,
+        result: Option<T>,
+    }
+
+    extern "C" fn call_closure<F, T>(data: *mut c_void) -> *mut c_void
+    where
+        F: FnOnce() -> T,
+    {
+        let closure = unsafe { &mut *(data as *mut Closure<F, T>) };
+        if let Some(f) = closure.f.take() {
+            closure.result = Some(f());
+        }
+        std::ptr::null_mut()
+    }
+
+    let mut closure = Closure {
+        f: Some(f),
+        result: None,
+    };
+
+    unsafe {
+        rb_thread_call_without_gvl(
+            Some(call_closure::<F, T>),
+            &mut closure as *mut _ as *mut c_void,
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+
+    closure.result.expect("closure did not run")
+}

data/ext/slatedb/src/snapshot.rs

@@ -0,0 +1,197 @@
+use std::cell::RefCell;
+use std::sync::Arc;
+
+use magnus::prelude::*;
+use magnus::{method, Error, RHash, Ruby};
+use slatedb::config::{DurabilityLevel, ReadOptions, ScanOptions};
+use slatedb::DbSnapshot;
+
+use crate::errors::{closed_error, invalid_argument_error, map_error};
+use crate::iterator::Iterator;
+use crate::runtime::block_on;
+use crate::utils::get_optional;
+
+/// Ruby wrapper for SlateDB Snapshot.
+///
+/// This struct is exposed to Ruby as `SlateDb::Snapshot`.
+/// Provides a consistent, read-only view of the database at a point in time.
+#[magnus::wrap(class = "SlateDb::Snapshot", free_immediately, size)]
+pub struct Snapshot {
+    inner: RefCell<Option<Arc<DbSnapshot>>>,
+}
+
+impl Snapshot {
+    /// Create a new Snapshot from a DbSnapshot.
+    pub fn new(snapshot: Arc<DbSnapshot>) -> Self {
+        Self {
+            inner: RefCell::new(Some(snapshot)),
+        }
+    }
+
+    /// Get a value by key from the snapshot.
+    pub fn get(&self, key: String) -> Result<Option<String>, Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let guard = self.inner.borrow();
+        let snapshot = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("snapshot is closed"))?;
+
+        let result = block_on(async { snapshot.get(key.as_bytes()).await }).map_err(map_error)?;
+
+        Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
+    }
+
+    /// Get a value by key with options from the snapshot.
+    pub fn get_with_options(&self, key: String, kwargs: RHash) -> Result<Option<String>, Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let mut opts = ReadOptions::default();
+
+        if let Some(df) = get_optional::<String>(&kwargs, "durability_filter")? {
+            opts.durability_filter = match df.as_str() {
+                "remote" => DurabilityLevel::Remote,
+                "memory" => DurabilityLevel::Memory,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid durability_filter: {} (expected 'remote' or 'memory')",
+                        other
+                    )))
+                }
+            };
+        }
+
+        if let Some(dirty) = get_optional::<bool>(&kwargs, "dirty")? {
+            opts.dirty = dirty;
+        }
+
+        let guard = self.inner.borrow();
+        let snapshot = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("snapshot is closed"))?;
+
+        let result = block_on(async { snapshot.get_with_options(key.as_bytes(), &opts).await })
+            .map_err(map_error)?;
+
+        Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
+    }
+
+    /// Scan a range of keys from the snapshot.
+    pub fn scan(&self, start: String, end_key: Option<String>) -> Result<Iterator, Error> {
+        if start.is_empty() {
+            return Err(invalid_argument_error("start key cannot be empty"));
+        }
+
+        let guard = self.inner.borrow();
+        let snapshot = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("snapshot is closed"))?;
+
+        let start_bytes = start.into_bytes();
+        let end_bytes = end_key.map(|e| e.into_bytes());
+
+        let iter = block_on(async {
+            let range = match end_bytes {
+                Some(end) => snapshot.scan(start_bytes..end).await,
+                None => snapshot.scan(start_bytes..).await,
+            };
+            range.map_err(map_error)
+        })?;
+
+        Ok(Iterator::new(iter))
+    }
+
+    /// Scan a range of keys with options from the snapshot.
+    pub fn scan_with_options(
+        &self,
+        start: String,
+        end_key: Option<String>,
+        kwargs: RHash,
+    ) -> Result<Iterator, Error> {
+        if start.is_empty() {
+            return Err(invalid_argument_error("start key cannot be empty"));
+        }
+
+        let mut opts = ScanOptions::default();
+
+        if let Some(df) = get_optional::<String>(&kwargs, "durability_filter")? {
+            opts.durability_filter = match df.as_str() {
+                "remote" => DurabilityLevel::Remote,
+                "memory" => DurabilityLevel::Memory,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid durability_filter: {} (expected 'remote' or 'memory')",
+                        other
+                    )))
+                }
+            };
+        }
+
+        if let Some(dirty) = get_optional::<bool>(&kwargs, "dirty")? {
+            opts.dirty = dirty;
+        }
+
+        if let Some(rab) = get_optional::<usize>(&kwargs, "read_ahead_bytes")? {
+            opts.read_ahead_bytes = rab;
+        }
+
+        if let Some(cb) = get_optional::<bool>(&kwargs, "cache_blocks")? {
+            opts.cache_blocks = cb;
+        }
+
+        if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
+            opts.max_fetch_tasks = mft;
+        }
+
+        let guard = self.inner.borrow();
+        let snapshot = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("snapshot is closed"))?;
+
+        let start_bytes = start.into_bytes();
+        let end_bytes = end_key.map(|e| e.into_bytes());
+
+        let iter = block_on(async {
+            let range = match end_bytes {
+                Some(end) => snapshot.scan_with_options(start_bytes..end, &opts).await,
+                None => snapshot.scan_with_options(start_bytes.., &opts).await,
+            };
+            range.map_err(map_error)
+        })?;
+
+        Ok(Iterator::new(iter))
+    }
+
+    /// Close the snapshot and release resources.
+    pub fn close(&self) -> Result<(), Error> {
+        let _ = self.inner.borrow_mut().take();
+        Ok(())
+    }
+
+    /// Check if the snapshot is closed.
+    pub fn is_closed(&self) -> bool {
+        self.inner.borrow().is_none()
+    }
+}
+
+/// Define the Snapshot class on the SlateDb module.
+pub fn define_snapshot_class(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("Snapshot", ruby.class_object())?;
+
+    // Instance methods
+    class.define_method("_get", method!(Snapshot::get, 1))?;
+    class.define_method("_get_with_options", method!(Snapshot::get_with_options, 2))?;
+    class.define_method("_scan", method!(Snapshot::scan, 2))?;
+    class.define_method(
+        "_scan_with_options",
+        method!(Snapshot::scan_with_options, 3),
+    )?;
+    class.define_method("close", method!(Snapshot::close, 0))?;
+    class.define_method("closed?", method!(Snapshot::is_closed, 0))?;
+
+    Ok(())
+}