slatedb 0.1.0

data/ext/slatedb/src/transaction.rs

@@ -0,0 +1,298 @@
+use std::cell::RefCell;
+
+use magnus::prelude::*;
+use magnus::{method, Error, RHash, Ruby};
+use slatedb::config::{DurabilityLevel, PutOptions, ReadOptions, ScanOptions, Ttl, WriteOptions};
+use slatedb::DBTransaction;
+
+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 Transaction.
+///
+/// This struct is exposed to Ruby as `SlateDb::Transaction`.
+/// After commit or rollback, the transaction is closed.
+#[magnus::wrap(class = "SlateDb::Transaction", free_immediately, size)]
+pub struct Transaction {
+    inner: RefCell<Option<DBTransaction>>,
+}
+
+impl Transaction {
+    /// Create a new Transaction from a DBTransaction.
+    pub fn new(txn: DBTransaction) -> Self {
+        Self {
+            inner: RefCell::new(Some(txn)),
+        }
+    }
+
+    /// Get a value by key within the transaction.
+    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 txn = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("transaction is closed"))?;
+
+        let result = block_on(async { txn.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 within the transaction.
+    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 txn = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("transaction is closed"))?;
+
+        let result = block_on(async { txn.get_with_options(key.as_bytes(), &opts).await })
+            .map_err(map_error)?;
+
+        Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
+    }
+
+    /// Put a key-value pair within the transaction.
+    pub fn put(&self, key: String, value: String) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let guard = self.inner.borrow();
+        let txn = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("transaction is closed"))?;
+
+        txn.put(key.as_bytes(), value.as_bytes())
+            .map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Put a key-value pair with options within the transaction.
+    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"));
+        }
+
+        let ttl = get_optional::<u64>(&kwargs, "ttl")?;
+        let put_opts = PutOptions {
+            ttl: match ttl {
+                Some(ms) => Ttl::ExpireAfter(ms),
+                None => Ttl::Default,
+            },
+        };
+
+        let guard = self.inner.borrow();
+        let txn = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("transaction is closed"))?;
+
+        txn.put_with_options(key.as_bytes(), value.as_bytes(), &put_opts)
+            .map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Delete a key within the transaction.
+    pub fn delete(&self, key: String) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        let guard = self.inner.borrow();
+        let txn = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("transaction is closed"))?;
+
+        txn.delete(key.as_bytes()).map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Scan a range of keys within the transaction.
+    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 txn = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("transaction 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) => txn.scan(start_bytes..end).await,
+                None => txn.scan(start_bytes..).await,
+            };
+            range.map_err(map_error)
+        })?;
+
+        Ok(Iterator::new(iter))
+    }
+
+    /// Scan a range of keys with options within the transaction.
+    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 txn = guard
+            .as_ref()
+            .ok_or_else(|| closed_error("transaction 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) => txn.scan_with_options(start_bytes..end, &opts).await,
+                None => txn.scan_with_options(start_bytes.., &opts).await,
+            };
+            range.map_err(map_error)
+        })?;
+
+        Ok(Iterator::new(iter))
+    }
+
+    /// Commit the transaction.
+    pub fn commit(&self) -> Result<(), Error> {
+        let txn = self
+            .inner
+            .borrow_mut()
+            .take()
+            .ok_or_else(|| closed_error("transaction is closed"))?;
+
+        block_on(async { txn.commit().await }).map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Commit the transaction with options.
+    pub fn commit_with_options(&self, kwargs: RHash) -> Result<(), Error> {
+        let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
+        let write_opts = WriteOptions { await_durable };
+
+        let txn = self
+            .inner
+            .borrow_mut()
+            .take()
+            .ok_or_else(|| closed_error("transaction is closed"))?;
+
+        block_on(async { txn.commit_with_options(&write_opts).await }).map_err(map_error)?;
+
+        Ok(())
+    }
+
+    /// Rollback the transaction (discard all changes).
+    pub fn rollback(&self) -> Result<(), Error> {
+        // Simply drop the transaction - changes are not committed
+        let _ = self.inner.borrow_mut().take();
+        Ok(())
+    }
+
+    /// Check if the transaction is closed.
+    pub fn is_closed(&self) -> bool {
+        self.inner.borrow().is_none()
+    }
+}
+
+/// Define the Transaction class on the SlateDb module.
+pub fn define_transaction_class(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("Transaction", ruby.class_object())?;
+
+    // Instance methods
+    class.define_method("_get", method!(Transaction::get, 1))?;
+    class.define_method(
+        "_get_with_options",
+        method!(Transaction::get_with_options, 2),
+    )?;
+    class.define_method("_put", method!(Transaction::put, 2))?;
+    class.define_method(
+        "_put_with_options",
+        method!(Transaction::put_with_options, 3),
+    )?;
+    class.define_method("_delete", method!(Transaction::delete, 1))?;
+    class.define_method("_scan", method!(Transaction::scan, 2))?;
+    class.define_method(
+        "_scan_with_options",
+        method!(Transaction::scan_with_options, 3),
+    )?;
+    class.define_method("commit", method!(Transaction::commit, 0))?;
+    class.define_method(
+        "_commit_with_options",
+        method!(Transaction::commit_with_options, 1),
+    )?;
+    class.define_method("rollback", method!(Transaction::rollback, 0))?;
+    class.define_method("closed?", method!(Transaction::is_closed, 0))?;
+
+    Ok(())
+}

data/ext/slatedb/src/utils.rs

@@ -0,0 +1,18 @@
+use magnus::value::ReprValue;
+use magnus::{Error, RHash, Ruby, TryConvert};
+
+/// Helper to extract an optional value from an RHash
+pub fn get_optional<T: TryConvert>(hash: &RHash, key: &str) -> Result<Option<T>, Error> {
+    let ruby = Ruby::get().expect("Ruby runtime not available");
+    let sym = ruby.to_symbol(key);
+    match hash.get(sym) {
+        Some(val) => {
+            if val.is_nil() {
+                Ok(None)
+            } else {
+                Ok(Some(T::try_convert(val)?))
+            }
+        }
+        None => Ok(None),
+    }
+}

data/ext/slatedb/src/write_batch.rs

@@ -0,0 +1,98 @@
+use std::cell::RefCell;
+
+use magnus::prelude::*;
+use magnus::{function, method, Error, RHash, Ruby};
+use slatedb::config::{PutOptions, Ttl};
+use slatedb::WriteBatch as SlateWriteBatch;
+
+use crate::errors::invalid_argument_error;
+use crate::utils::get_optional;
+
+/// Ruby wrapper for SlateDB WriteBatch.
+///
+/// This struct is exposed to Ruby as `SlateDb::WriteBatch`.
+#[magnus::wrap(class = "SlateDb::WriteBatch", free_immediately, size)]
+pub struct WriteBatch {
+    inner: RefCell<SlateWriteBatch>,
+}
+
+impl WriteBatch {
+    /// Create a new empty WriteBatch.
+    pub fn new() -> Self {
+        Self {
+            inner: RefCell::new(SlateWriteBatch::new()),
+        }
+    }
+
+    /// Add a put operation to the batch.
+    pub fn put(&self, key: String, value: String) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        self.inner
+            .borrow_mut()
+            .put(key.as_bytes(), value.as_bytes());
+
+        Ok(())
+    }
+
+    /// Add a put operation with options to the batch.
+    ///
+    /// Options:
+    /// - ttl: Time-to-live in milliseconds
+    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"));
+        }
+
+        let ttl = get_optional::<u64>(&kwargs, "ttl")?;
+        let put_opts = PutOptions {
+            ttl: match ttl {
+                Some(ms) => Ttl::ExpireAfter(ms),
+                None => Ttl::Default,
+            },
+        };
+
+        self.inner
+            .borrow_mut()
+            .put_with_options(key.as_bytes(), value.as_bytes(), &put_opts);
+
+        Ok(())
+    }
+
+    /// Add a delete operation to the batch.
+    pub fn delete(&self, key: String) -> Result<(), Error> {
+        if key.is_empty() {
+            return Err(invalid_argument_error("key cannot be empty"));
+        }
+
+        self.inner.borrow_mut().delete(key.as_bytes());
+
+        Ok(())
+    }
+
+    /// Take ownership of the inner WriteBatch (consumes it).
+    /// Used internally when writing the batch to the database.
+    pub fn take(&self) -> Result<SlateWriteBatch, Error> {
+        Ok(self.inner.replace(SlateWriteBatch::new()))
+    }
+}
+
+/// Define the WriteBatch class on the SlateDb module.
+pub fn define_write_batch_class(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("WriteBatch", ruby.class_object())?;
+
+    // Class methods
+    class.define_singleton_method("new", function!(WriteBatch::new, 0))?;
+
+    // Instance methods
+    class.define_method("_put", method!(WriteBatch::put, 2))?;
+    class.define_method(
+        "_put_with_options",
+        method!(WriteBatch::put_with_options, 3),
+    )?;
+    class.define_method("_delete", method!(WriteBatch::delete, 1))?;
+
+    Ok(())
+}

data/lib/slatedb/admin.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module SlateDb
+  class Admin
+    class << self
+      # Create an admin handle for a database path/object store.
+      #
+      # @param path [String] Database path
+      # @param url [String, nil] Optional object store URL
+      # @return [Admin] The admin handle
+      #
+      # @example
+      #   admin = SlateDb::Admin.new("/tmp/mydb")
+      #   checkpoints = admin.list_checkpoints
+      #
+      def new(path, url: nil)
+        _new(path, url)
+      end
+    end
+
+    # Read the latest or a specific manifest as a JSON string.
+    #
+    # @param id [Integer, nil] Optional manifest id to read. If nil, reads the latest.
+    # @return [String, nil] JSON string of the manifest, or nil if no manifests exist
+    #
+    # @example
+    #   json = admin.read_manifest
+    #   json = admin.read_manifest(123)
+    #
+    def read_manifest(id = nil)
+      _read_manifest(id)
+    end
+
+    # List manifests within an optional [start, end) range as JSON.
+    #
+    # @param start [Integer, nil] Optional inclusive start id
+    # @param end_id [Integer, nil] Optional exclusive end id
+    # @return [String] JSON string containing a list of manifest metadata
+    #
+    # @example
+    #   json = admin.list_manifests
+    #   json = admin.list_manifests(start: 1, end_id: 10)
+    #
+    def list_manifests(start: nil, end_id: nil)
+      _list_manifests(start, end_id)
+    end
+
+    # Create a detached checkpoint.
+    #
+    # @param lifetime [Integer, nil] Checkpoint lifetime in milliseconds
+    # @param source [String, nil] Source checkpoint UUID string to extend/refresh
+    # @param name [String, nil] Checkpoint name
+    # @return [Hash] Hash with :id (UUID string) and :manifest_id (Integer)
+    #
+    # @example
+    #   result = admin.create_checkpoint(name: "my_checkpoint")
+    #   puts result[:id]         # => "uuid-string"
+    #   puts result[:manifest_id] # => 7
+    #
+    def create_checkpoint(lifetime: nil, source: nil, name: nil)
+      opts = {}
+      opts[:lifetime] = lifetime if lifetime
+      opts[:source] = source if source
+      opts[:name] = name if name
+      _create_checkpoint(opts)
+    end
+
+    # List known checkpoints for the database.
+    #
+    # @param name [String, nil] Optional checkpoint name filter
+    # @return [Array<Hash>] Array of checkpoint hashes
+    #
+    # @example
+    #   checkpoints = admin.list_checkpoints
+    #   checkpoints.each do |cp|
+    #     puts "#{cp[:id]}: #{cp[:name]}"
+    #   end
+    #
+    def list_checkpoints(name: nil)
+      _list_checkpoints(name)
+    end
+
+    # Refresh a checkpoint's lifetime.
+    #
+    # @param id [String] Checkpoint UUID string
+    # @param lifetime [Integer, nil] New lifetime in milliseconds
+    # @return [void]
+    #
+    # @example
+    #   admin.refresh_checkpoint("uuid-here", lifetime: 60_000)
+    #
+    def refresh_checkpoint(id, lifetime: nil)
+      _refresh_checkpoint(id, lifetime)
+    end
+
+    # Delete a checkpoint.
+    #
+    # @param id [String] Checkpoint UUID string
+    # @return [void]
+    #
+    # @example
+    #   admin.delete_checkpoint("uuid-here")
+    #
+    def delete_checkpoint(id)
+      _delete_checkpoint(id)
+    end
+
+    # Run garbage collection once.
+    #
+    # @param min_age [Integer, nil] Minimum age in milliseconds for objects to be collected
+    # @return [void]
+    #
+    # @example
+    #   admin.run_gc(min_age: 3600_000) # 1 hour
+    #
+    def run_gc(min_age: nil)
+      opts = {}
+      opts[:min_age] = min_age if min_age
+      _run_gc(opts)
+    end
+  end
+end