slatedb 0.1.0

data/ext/slatedb/src/database.rs

@@ -0,0 +1,457 @@
+use std::sync::Arc;
+
+use magnus::prelude::*;
+use magnus::{function, method, Error, RHash, Ruby};
+use slatedb::config::{DurabilityLevel, PutOptions, ReadOptions, ScanOptions, Ttl, WriteOptions};
+use slatedb::object_store::memory::InMemory;
+use slatedb::{Db, IsolationLevel};
+
+use crate::errors::{invalid_argument_error, map_error};
+use crate::iterator::Iterator;
+use crate::runtime::block_on;
+use crate::snapshot::Snapshot;
+use crate::transaction::Transaction;
+use crate::utils::get_optional;
+use crate::write_batch::WriteBatch;
+
+/// Ruby wrapper for SlateDB database.
+///
+/// This struct is exposed to Ruby as `SlateDb::Database`.
+#[magnus::wrap(class = "SlateDb::Database", free_immediately, size)]
+pub struct Database {
+    inner: Arc<Db>,
+}
+
+impl Database {
+    /// Open a database at the given path.
+    ///
+    /// # Arguments
+    /// * `path` - The path identifier for the database
+    /// * `url` - Optional object store URL (e.g., "s3://bucket/path")
+    ///
+    /// # Returns
+    /// A new Database instance
+    pub fn open(path: String, url: Option<String>) -> Result<Self, Error> {
+        let db = block_on(async {
+            let object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url) = url {
+                Db::resolve_object_store(url).map_err(map_error)?
+            } else {
+                // Use in-memory store for local testing
+                Arc::new(InMemory::new())
+            };
+
+            Db::builder(path, object_store)
+                .build()
+                .await
+                .map_err(map_error)
+        })?;
+
+        Ok(Self {
+            inner: Arc::new(db),
+        })
+    }
+
+    /// Get a value by key.
+    ///
+    /// # Arguments
+    /// * `key` - The key to look up
+    ///
+    /// # Returns
+    /// The value as a String, or nil if not found
+    pub fn get(&self, key: String) -> Result<Option<String>, Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let opts = ReadOptions::default();
+
+        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 with options.
+    ///
+    /// # Arguments
+    /// * `key` - The key to look up
+    /// * `kwargs` - Keyword arguments (durability_filter, dirty, cache_blocks)
+    ///
+    /// # Returns
+    /// The value as a String, or nil if not found
+    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();
+
+        // Parse durability_filter
+        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
+                    )))
+                }
+            };
+        }
+
+        // Parse dirty
+        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.
+    ///
+    /// # Arguments
+    /// * `key` - The key to look up
+    ///
+    /// # Returns
+    /// The value as bytes, or nil if not found
+    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 opts = ReadOptions::default();
+
+        let result = block_on(async { self.inner.get_with_options(key.as_bytes(), &opts).await })
+            .map_err(map_error)?;
+
+        Ok(result.map(|b| b.to_vec()))
+    }
+
+    /// Store a key-value pair.
+    ///
+    /// # Arguments
+    /// * `key` - The key to store
+    /// * `value` - The value to store
+    pub fn put(&self, key: String, value: String) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let put_opts = PutOptions { ttl: Ttl::Default };
+
+        let write_opts = WriteOptions {
+            await_durable: true,
+        };
+
+        block_on(async {
+            self.inner
+                .put_with_options(key.as_bytes(), value.as_bytes(), &put_opts, &write_opts)
+                .await
+        })
+        .map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Store a key-value pair with options.
+    ///
+    /// # Arguments
+    /// * `key` - The key to store
+    /// * `value` - The value to store
+    /// * `kwargs` - Keyword arguments (ttl, await_durable)
+    pub fn put_with_options(&self, key: String, value: String, kwargs: RHash) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        // Parse ttl
+        let ttl = get_optional::<u64>(&kwargs, "ttl")?;
+        let put_opts = PutOptions {
+            ttl: match ttl {
+                Some(ms) => Ttl::ExpireAfter(ms),
+                None => Ttl::Default,
+            },
+        };
+
+        // Parse await_durable
+        let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
+        let write_opts = WriteOptions { await_durable };
+
+        block_on(async {
+            self.inner
+                .put_with_options(key.as_bytes(), value.as_bytes(), &put_opts, &write_opts)
+                .await
+        })
+        .map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Delete a key.
+    ///
+    /// # Arguments
+    /// * `key` - The key to delete
+    pub fn delete(&self, key: String) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let write_opts = WriteOptions {
+            await_durable: true,
+        };
+
+        block_on(async {
+            self.inner
+                .delete_with_options(key.as_bytes(), &write_opts)
+                .await
+        })
+        .map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Delete a key with options.
+    ///
+    /// # Arguments
+    /// * `key` - The key to delete
+    /// * `kwargs` - Keyword arguments (await_durable)
+    pub fn delete_with_options(&self, key: String, kwargs: RHash) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
+        let write_opts = WriteOptions { await_durable };
+
+        block_on(async {
+            self.inner
+                .delete_with_options(key.as_bytes(), &write_opts)
+                .await
+        })
+        .map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Scan a range of keys.
+    ///
+    /// # Arguments
+    /// * `start` - The start key (inclusive)
+    /// * `end_key` - Optional end key (exclusive). If not provided, scans to end.
+    ///
+    /// # Returns
+    /// An Iterator over key-value pairs
+    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 opts = ScanOptions::default();
+
+        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))
+    }
+
+    /// Scan a range of keys with options.
+    ///
+    /// # Arguments
+    /// * `start` - The start key (inclusive)
+    /// * `end_key` - Optional end key (exclusive)
+    /// * `kwargs` - Keyword arguments (durability_filter, dirty, read_ahead_bytes, cache_blocks, max_fetch_tasks)
+    ///
+    /// # Returns
+    /// An Iterator over key-value pairs
+    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();
+
+        // Parse durability_filter
+        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
+                    )))
+                }
+            };
+        }
+
+        // Parse dirty
+        if let Some(dirty) = get_optional::<bool>(&kwargs, "dirty")? {
+            opts.dirty = dirty;
+        }
+
+        // Parse read_ahead_bytes
+        if let Some(rab) = get_optional::<usize>(&kwargs, "read_ahead_bytes")? {
+            opts.read_ahead_bytes = rab;
+        }
+
+        // Parse cache_blocks
+        if let Some(cb) = get_optional::<bool>(&kwargs, "cache_blocks")? {
+            opts.cache_blocks = cb;
+        }
+
+        // Parse max_fetch_tasks
+        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))
+    }
+
+    /// Write a batch of operations atomically.
+    ///
+    /// # Arguments
+    /// * `batch` - The WriteBatch to write
+    pub fn write(&self, batch: &WriteBatch) -> Result<(), Error> {
+        let batch_inner = batch.take()?;
+
+        block_on(async { self.inner.write(batch_inner).await }).map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Write a batch of operations atomically with options.
+    ///
+    /// # Arguments
+    /// * `batch` - The WriteBatch to write
+    /// * `kwargs` - Keyword arguments (await_durable)
+    pub fn write_with_options(&self, batch: &WriteBatch, kwargs: RHash) -> Result<(), Error> {
+        let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
+        let write_opts = WriteOptions { await_durable };
+
+        let batch_inner = batch.take()?;
+
+        block_on(async {
+            self.inner
+                .write_with_options(batch_inner, &write_opts)
+                .await
+        })
+        .map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Begin a new transaction.
+    ///
+    /// # Arguments
+    /// * `isolation` - Optional isolation level ("snapshot" or "serializable")
+    ///
+    /// # Returns
+    /// A new Transaction instance
+    pub fn begin_transaction(&self, isolation: Option<String>) -> Result<Transaction, Error> {
+        let isolation_level = match isolation.as_deref().unwrap_or("snapshot") {
+            "snapshot" | "si" => IsolationLevel::Snapshot,
+            "serializable" | "ssi" | "serializable_snapshot" => {
+                IsolationLevel::SerializableSnapshot
+            }
+            other => {
+                return Err(invalid_argument_error(&format!(
+                    "invalid isolation level: {} (expected 'snapshot' or 'serializable')",
+                    other
+                )))
+            }
+        };
+
+        let txn = block_on(async { self.inner.begin(isolation_level).await }).map_err(map_error)?;
+
+        Ok(Transaction::new(txn))
+    }
+
+    /// Create a snapshot for consistent reads.
+    ///
+    /// # Returns
+    /// A new Snapshot instance
+    pub fn snapshot(&self) -> Result<Snapshot, Error> {
+        let snap = block_on(async { self.inner.snapshot().await }).map_err(map_error)?;
+
+        Ok(Snapshot::new(snap))
+    }
+
+    /// Flush the database to ensure durability.
+    pub fn flush(&self) -> Result<(), Error> {
+        block_on(async { self.inner.flush().await }).map_err(map_error)?;
+        Ok(())
+    }
+
+    /// Close the database.
+    pub fn close(&self) -> Result<(), Error> {
+        block_on(async { self.inner.close().await }).map_err(map_error)?;
+        Ok(())
+    }
+}
+
+/// Define the Database class on the SlateDb module.
+pub fn define_database_class(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("Database", ruby.class_object())?;
+
+    // Class methods
+    class.define_singleton_method("_open", function!(Database::open, 2))?;
+
+    // Instance methods - simple versions
+    class.define_method("_get", method!(Database::get, 1))?;
+    class.define_method("_get_with_options", method!(Database::get_with_options, 2))?;
+    class.define_method("get_bytes", method!(Database::get_bytes, 1))?;
+    class.define_method("_put", method!(Database::put, 2))?;
+    class.define_method("_put_with_options", method!(Database::put_with_options, 3))?;
+    class.define_method("_delete", method!(Database::delete, 1))?;
+    class.define_method(
+        "_delete_with_options",
+        method!(Database::delete_with_options, 2),
+    )?;
+    class.define_method("_scan", method!(Database::scan, 2))?;
+    class.define_method(
+        "_scan_with_options",
+        method!(Database::scan_with_options, 3),
+    )?;
+    class.define_method("_write", method!(Database::write, 1))?;
+    class.define_method(
+        "_write_with_options",
+        method!(Database::write_with_options, 2),
+    )?;
+    class.define_method(
+        "_begin_transaction",
+        method!(Database::begin_transaction, 1),
+    )?;
+    class.define_method("_snapshot", method!(Database::snapshot, 0))?;
+    class.define_method("flush", method!(Database::flush, 0))?;
+    class.define_method("close", method!(Database::close, 0))?;
+
+    Ok(())
+}

data/ext/slatedb/src/errors.rs

@@ -0,0 +1,144 @@
+use magnus::prelude::*;
+use magnus::{Error, ExceptionClass, Ruby};
+use slatedb::Error as SlateError;
+use slatedb::ErrorKind;
+use std::cell::RefCell;
+
+// Store exception classes in thread-local storage for access during error mapping
+thread_local! {
+    static SLATE_DB_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static TRANSACTION_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static CLOSED_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static UNAVAILABLE_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static INVALID_ARGUMENT_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static DATA_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static INTERNAL_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+}
+
+/// Define SlateDB exception classes under the SlateDb module.
+///
+/// Exception hierarchy:
+/// - SlateDb::Error (base class, inherits from StandardError)
+///   - SlateDb::TransactionError
+///   - SlateDb::ClosedError
+///   - SlateDb::UnavailableError
+///   - SlateDb::InvalidArgumentError
+///   - SlateDb::DataError
+///   - SlateDb::InternalError
+pub fn define_exceptions(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let standard_error = ruby.exception_standard_error();
+
+    // Define base SlateDb::Error
+    let slate_error = module.define_error("Error", standard_error)?;
+    SLATE_DB_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(slate_error);
+    });
+
+    // Define specific error types
+    let transaction_error = module.define_error("TransactionError", slate_error)?;
+    TRANSACTION_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(transaction_error);
+    });
+
+    let closed_error = module.define_error("ClosedError", slate_error)?;
+    CLOSED_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(closed_error);
+    });
+
+    let unavailable_error = module.define_error("UnavailableError", slate_error)?;
+    UNAVAILABLE_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(unavailable_error);
+    });
+
+    let invalid_argument_error = module.define_error("InvalidArgumentError", slate_error)?;
+    INVALID_ARGUMENT_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(invalid_argument_error);
+    });
+
+    let data_error = module.define_error("DataError", slate_error)?;
+    DATA_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(data_error);
+    });
+
+    let internal_error = module.define_error("InternalError", slate_error)?;
+    INTERNAL_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(internal_error);
+    });
+
+    Ok(())
+}
+
+/// Map a SlateDB error to the appropriate Ruby exception.
+pub fn map_error(err: SlateError) -> Error {
+    let msg = format!("{}", err);
+    let ruby = Ruby::get().expect("Ruby runtime not available");
+
+    match err.kind() {
+        ErrorKind::Transaction => TRANSACTION_ERROR.with(|cell| {
+            cell.borrow()
+                .map(|exc| Error::new(exc, msg.clone()))
+                .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.clone()))
+        }),
+        ErrorKind::Closed(_) => CLOSED_ERROR.with(|cell| {
+            cell.borrow()
+                .map(|exc| Error::new(exc, msg.clone()))
+                .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.clone()))
+        }),
+        ErrorKind::Unavailable => UNAVAILABLE_ERROR.with(|cell| {
+            cell.borrow()
+                .map(|exc| Error::new(exc, msg.clone()))
+                .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.clone()))
+        }),
+        ErrorKind::Invalid => INVALID_ARGUMENT_ERROR.with(|cell| {
+            cell.borrow()
+                .map(|exc| Error::new(exc, msg.clone()))
+                .unwrap_or_else(|| Error::new(ruby.exception_arg_error(), msg.clone()))
+        }),
+        ErrorKind::Data => DATA_ERROR.with(|cell| {
+            cell.borrow()
+                .map(|exc| Error::new(exc, msg.clone()))
+                .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.clone()))
+        }),
+        ErrorKind::Internal => INTERNAL_ERROR.with(|cell| {
+            cell.borrow()
+                .map(|exc| Error::new(exc, msg.clone()))
+                .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.clone()))
+        }),
+        _ => INTERNAL_ERROR.with(|cell| {
+            cell.borrow()
+                .map(|exc| Error::new(exc, msg.clone()))
+                .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.clone()))
+        }),
+    }
+}
+
+/// Create an InvalidArgumentError with the given message.
+pub fn invalid_argument_error(msg: &str) -> Error {
+    let ruby = Ruby::get().expect("Ruby runtime not available");
+    INVALID_ARGUMENT_ERROR.with(|cell| {
+        cell.borrow()
+            .map(|exc| Error::new(exc, msg.to_string()))
+            .unwrap_or_else(|| Error::new(ruby.exception_arg_error(), msg.to_string()))
+    })
+}
+
+/// Create an InternalError with the given message.
+#[allow(dead_code)]
+pub fn internal_error(msg: &str) -> Error {
+    let ruby = Ruby::get().expect("Ruby runtime not available");
+    INTERNAL_ERROR.with(|cell| {
+        cell.borrow()
+            .map(|exc| Error::new(exc, msg.to_string()))
+            .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.to_string()))
+    })
+}
+
+/// Create a ClosedError with the given message.
+pub fn closed_error(msg: &str) -> Error {
+    let ruby = Ruby::get().expect("Ruby runtime not available");
+    CLOSED_ERROR.with(|cell| {
+        cell.borrow()
+            .map(|exc| Error::new(exc, msg.to_string()))
+            .unwrap_or_else(|| Error::new(ruby.exception_runtime_error(), msg.to_string()))
+    })
+}