beagle-turso 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f35de8fc3b33e04d7d170ee1032ee2d57af85642fcec1b120d591700baa9532c
-  data.tar.gz: 67bbe8aaa50468fb2cf0ef2c44e208fd414c4dff3694e9ae2a8dc8394ae671b7
+  metadata.gz: e153a3302d14dc6f72dcd76b510a0dadb1e16f4f50235258fd81a6ef67be4e91
+  data.tar.gz: b52eeb81d1fb68ce40efbe8691202f8c70e9cdceb6491fdce31ad58e4a6714d6
 SHA512:
-  metadata.gz: ce2cef361285eed71718e587fbbe3a1a3d321e2e45ba269b1274edbbc622d073a0b55274ea2950e89e67eafeaceb70a0f3e469e0bd0bf29b59ac2ffedc205095
-  data.tar.gz: edd3d0df3ce5ba628e4ca6923c9df228c9f480d9a05ba4bf879f95a599adeed5d362f38f10b8621ee1d0fa01a0ca07ae1a69e9b85065c0fd089b59e3510706be
+  metadata.gz: bef6dc8666bdf7b163eb8b2c710b61b4db7cb33ee2b914b8c60904b2c13a333fb0a656f780ad6e909b186e273b1dc113558b5a0161b55c5cf8473760bcddc3b0
+  data.tar.gz: fd867e70cc1657e4c5922cf635b80eb4bade93805f41fcd343353975a582812bb18b7b405ecc3ec538fada798d665d76b2409e01ec09d83b4e588869631cd7ce

data/README.md

@@ -68,7 +68,8 @@ db.pull # pull remote changes down to the local file (returns true/false)
 `Database.open` also accepts `bootstrap_if_empty:` (defaults to `true`),
 which pulls all remote data down on first open if the local file is new/empty.
 Calling `push`/`pull` on a database opened via `open_local` (or via `open`
-without both `remote_url:` and `auth_token:`) raises `RuntimeError`.
+without both `remote_url:` and `auth_token:`) raises
+`Beagle::Turso::NotSyncedError`.
 
 ### Durability note: writes commit on-sync, not synchronously
 
@@ -103,6 +104,54 @@ Two things to avoid:
 A single remote database, dedicated to this engine and written by one process
 at a time, is the model it's built for.
 
+## Errors
+
+Every error the driver raises is a `Beagle::Turso::Error`, a `RuntimeError`
+subclass: `OpenError`, `ConnectError`, `QueryError`, `SyncError`,
+`NotSyncedError` (push/pull on a local-only database), `BusyError` (another
+session or process holds the database), `ClosedError` and `ForkedError`. An
+unsupported bind parameter type raises Ruby's `TypeError`. Auth, network and
+protocol failures during sync all arrive as `SyncError` (or `OpenError` at
+open): the engine does not distinguish them. Messages never contain the auth
+token.
+
+Busy conditions now raise `BusyError` with a message beginning
+`database is busy:` (0.1.x said `query failed:` / `sync failed:`); it is
+still a `RuntimeError`. A replica file already held by another process raises
+`OpenError` ("... File is locked by another process").
+
+## Threads, fibers and fork
+
+- One `Database` may be shared by threads. Give each thread its own
+  `Connection`; a shared `Connection` works but serializes its callers.
+- `open`, `connect`, `push` and `pull` release the GVL, so other threads keep
+  running while they wait on the network. Queries keep it; they are local and
+  fast.
+- While one thread pushes, `closed?` returns immediately on other threads, and
+  queries on other connections proceed.
+- On a synced database, `connect` called while another thread is pushing waits
+  inside the engine until the push finishes (about the push's duration); the
+  GVL is released while it waits, so other threads and fibers keep running.
+  Open connections up front (e.g. at boot / pool warm-up) rather than per
+  request.
+- `close` during an in-flight `push` is safe: the push finishes or raises, and
+  later calls raise `ClosedError`.
+- A blocked native call cannot be interrupted: `Timeout` and `Thread#kill`
+  take effect when it returns.
+- **Falcon / Async:** on Ruby 4.0+ with `async` 2.25+ (enable its worker pool
+  with `ASYNC_SCHEDULER_WORKER_POOL=true` or
+  `Async::Scheduler.new(worker_pool: true)`), a fiber scheduler runs these
+  calls on a worker thread, so the reactor keeps serving other requests during
+  a sync. On Ruby 3.3/3.4 the GVL is still released, but the scheduler's own
+  thread blocks. Run sync from a dedicated thread there. Run one Falcon
+  process per replica (`--count 1`): the replica file is locked to one
+  process.
+- **Fork:** handles are bound to the process that opened them. In a forked
+  child, `open`, `connect`, `push`, `pull` and queries on an inherited handle
+  raise `ForkedError`; open a new database there. `close` is a no-op and
+  `closed?` is safe (it reports the handle as closed if it can't be inspected),
+  so inherited handles need no cleanup in the child.
+
 ## Credential safety
 
 `auth_token` is never included in `inspect` output or in error messages —

data/ext/beagle_turso/Cargo.toml

@@ -8,5 +8,6 @@ publish = false
 crate-type = ["cdylib"]
 
 [dependencies]
-magnus = "0.8"
-beagle_turso_core = "0.1.3"
+magnus = { version = "0.8", features = ["rb-sys"] }
+beagle_turso_core = "0.2.0"
+rb-sys = "0.9"

data/ext/beagle_turso/src/errors.rs

@@ -0,0 +1,30 @@
+// Maps beagle_turso_core errors onto the Ruby hierarchy defined in
+// lib/beagle/turso/errors.rb. Classes are looked up by name at raise time
+// (the error path only), so the Ruby file stays the single definition.
+
+use beagle_turso_core::Error as CoreError;
+use magnus::{exception::ExceptionClass, prelude::*, Error, RModule, Ruby};
+
+pub fn error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
+    ruby.class_object()
+        .const_get::<_, RModule>("Beagle")
+        .and_then(|m| m.const_get::<_, RModule>("Turso"))
+        .and_then(|m| m.const_get::<_, ExceptionClass>(name))
+        .unwrap_or_else(|_| ruby.exception_runtime_error())
+}
+
+pub fn raise_core(ruby: &Ruby, e: CoreError) -> Error {
+    let name = match &e {
+        CoreError::Open(_) => "OpenError",
+        CoreError::Connect(_) => "ConnectError",
+        CoreError::Query(_) => "QueryError",
+        CoreError::Sync(_) => "SyncError",
+        CoreError::NotSynced(_) => "NotSyncedError",
+        CoreError::Busy(_) => "BusyError",
+        CoreError::Closed => "ClosedError",
+        CoreError::Forked { .. } => "ForkedError",
+        // Value conversion problems stay Ruby's TypeError, as in 0.1.x.
+        CoreError::Type(_) => return Error::new(ruby.exception_type_error(), e.to_string()),
+    };
+    Error::new(error_class(ruby, name), e.to_string())
+}

data/ext/beagle_turso/src/lib.rs

@@ -14,7 +14,17 @@
 // identical; the code is simpler and compiles with zero deprecation
 // warnings.
 
+// GVL: open_local, open, connect, push and pull (the calls that can wait on the
+// network or disk for a long time) run via nogvl::without_gvl with the GVL
+// released. Queries/execute stay under the GVL: they are short, local, and
+// release/reacquire would cost more than it saves.
+
+mod errors;
+mod nogvl;
+
 use beagle_turso_core::{Connection, Database, OpenOptions, Value};
+use errors::raise_core;
+use nogvl::without_gvl;
 use magnus::{
     encoding::EncodingCapable, function, method, prelude::*, Error, Float, Integer, IntoValue,
     RArray, RString, Ruby,
@@ -30,10 +40,6 @@ struct RbConnection {
     inner: Connection,
 }
 
-fn rt_err(ruby: &Ruby, msg: String) -> Error {
-    Error::new(ruby.exception_runtime_error(), msg)
-}
-
 fn ruby_array_to_params(ruby: &Ruby, arr: RArray) -> Result<Vec<Value>, Error> {
     // Safe: `from_value` below is a raw type check on the Ruby object (exact
     // class match — no `to_int`/`to_f`/`to_str` coercion method dispatch), so
@@ -92,7 +98,7 @@ impl RbDatabase {
             auth_token: None,
             bootstrap_if_empty: true,
         };
-        let db = Database::open(opts).map_err(|e| rt_err(ruby, e.to_string()))?;
+        let db = without_gvl(|| Database::open(opts))?.map_err(|e| raise_core(ruby, e))?;
         Ok(RbDatabase { inner: db })
     }
 
@@ -113,30 +119,24 @@ impl RbDatabase {
             auth_token,
             bootstrap_if_empty,
         };
-        let db = Database::open(opts).map_err(|e| rt_err(ruby, e.to_string()))?;
+        let db = without_gvl(|| Database::open(opts))?.map_err(|e| raise_core(ruby, e))?;
         Ok(RbDatabase { inner: db })
     }
 
     fn connect(ruby: &Ruby, rb_self: &Self) -> Result<RbConnection, Error> {
-        let c = rb_self
-            .inner
-            .connect()
-            .map_err(|e| rt_err(ruby, e.to_string()))?;
+        let inner = &rb_self.inner;
+        let c = without_gvl(|| inner.connect())?.map_err(|e| raise_core(ruby, e))?;
         Ok(RbConnection { inner: c })
     }
 
     fn push(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
-        rb_self
-            .inner
-            .push()
-            .map_err(|e| rt_err(ruby, e.to_string()))
+        let inner = &rb_self.inner;
+        without_gvl(|| inner.push())?.map_err(|e| raise_core(ruby, e))
     }
 
     fn pull(ruby: &Ruby, rb_self: &Self) -> Result<bool, Error> {
-        rb_self
-            .inner
-            .pull()
-            .map_err(|e| rt_err(ruby, e.to_string()))
+        let inner = &rb_self.inner;
+        without_gvl(|| inner.pull())?.map_err(|e| raise_core(ruby, e))
     }
 
     // Release the underlying engine handle and, for a synced database, end its
@@ -151,13 +151,25 @@ impl RbDatabase {
     }
 }
 
+fn rows_to_ruby(ruby: &Ruby, rows: Vec<beagle_turso_core::Row>) -> Result<RArray, Error> {
+    let out = ruby.ary_new();
+    for row in rows {
+        let rb_row = ruby.ary_new();
+        for val in &row.values {
+            rb_row.push(value_to_ruby(ruby, val))?;
+        }
+        out.push(rb_row)?;
+    }
+    Ok(out)
+}
+
 impl RbConnection {
     fn execute(ruby: &Ruby, rb_self: &Self, sql: String, params: RArray) -> Result<u64, Error> {
         let p = ruby_array_to_params(ruby, params)?;
         rb_self
             .inner
             .execute(&sql, &p)
-            .map_err(|e| rt_err(ruby, e.to_string()))
+            .map_err(|e| raise_core(ruby, e))
     }
 
     fn query(ruby: &Ruby, rb_self: &Self, sql: String, params: RArray) -> Result<RArray, Error> {
@@ -165,16 +177,8 @@ impl RbConnection {
         let rows = rb_self
             .inner
             .query(&sql, &p)
-            .map_err(|e| rt_err(ruby, e.to_string()))?;
-        let out = ruby.ary_new();
-        for row in rows {
-            let rb_row = ruby.ary_new();
-            for val in &row.values {
-                rb_row.push(value_to_ruby(ruby, val))?;
-            }
-            out.push(rb_row)?;
-        }
-        Ok(out)
+            .map_err(|e| raise_core(ruby, e))?;
+        rows_to_ruby(ruby, rows)
     }
 
     // Like `query`, but also returns column names — needed by callers (e.g.
@@ -191,37 +195,59 @@ impl RbConnection {
         let result = rb_self
             .inner
             .query_result(&sql, &p)
-            .map_err(|e| rt_err(ruby, e.to_string()))?;
+            .map_err(|e| raise_core(ruby, e))?;
         let columns = ruby.ary_new();
         for name in &result.columns {
             columns.push(name.clone().into_value_with(ruby))?;
         }
-        let rows = ruby.ary_new();
-        for row in result.rows {
-            let rb_row = ruby.ary_new();
-            for val in &row.values {
-                rb_row.push(value_to_ruby(ruby, val))?;
-            }
-            rows.push(rb_row)?;
-        }
+        let rows = rows_to_ruby(ruby, result.rows)?;
         let out = ruby.ary_new();
         out.push(columns)?;
         out.push(rows)?;
         Ok(out)
     }
 
+    // Like `query_result`, plus each column's declared type (String or nil),
+    // which a Sequel adapter needs to pick value conversions. Returns
+    // `[columns, decl_types, rows]`.
+    fn query_result_with_types(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sql: String,
+        params: RArray,
+    ) -> Result<RArray, Error> {
+        let p = ruby_array_to_params(ruby, params)?;
+        let result = rb_self
+            .inner
+            .query_result(&sql, &p)
+            .map_err(|e| raise_core(ruby, e))?;
+        let columns = ruby.ary_new();
+        for name in result.columns {
+            columns.push(name)?;
+        }
+        let types = ruby.ary_new();
+        for t in result.decl_types {
+            types.push(t)?; // Option<String> -> String or nil
+        }
+        let out = ruby.ary_new();
+        out.push(columns)?;
+        out.push(types)?;
+        out.push(rows_to_ruby(ruby, result.rows)?)?;
+        Ok(out)
+    }
+
     fn last_insert_rowid(ruby: &Ruby, rb_self: &Self) -> Result<i64, Error> {
         rb_self
             .inner
             .last_insert_rowid()
-            .map_err(|e| rt_err(ruby, e.to_string()))
+            .map_err(|e| raise_core(ruby, e))
     }
 
     fn execute_batch(ruby: &Ruby, rb_self: &Self, sql: String) -> Result<(), Error> {
         rb_self
             .inner
             .execute_batch(&sql)
-            .map_err(|e| rt_err(ruby, e.to_string()))
+            .map_err(|e| raise_core(ruby, e))
     }
 
     // Release the underlying connection handle instead of waiting for GC.
@@ -253,6 +279,10 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     conn.define_method("execute", method!(RbConnection::execute, 2))?;
     conn.define_method("query", method!(RbConnection::query, 2))?;
     conn.define_method("query_result", method!(RbConnection::query_result, 2))?;
+    conn.define_method(
+        "query_result_with_types",
+        method!(RbConnection::query_result_with_types, 2),
+    )?;
     conn.define_method(
         "last_insert_rowid",
         method!(RbConnection::last_insert_rowid, 0),

data/ext/beagle_turso/src/nogvl.rs

@@ -0,0 +1,63 @@
+// Runs blocking Rust work with Ruby's GVL released, so other Ruby threads keep
+// running and a fiber scheduler that implements `blocking_operation_wait` can
+// move the call to a worker thread (keeping its reactor live).
+//
+// The closure must not touch any Ruby object: convert arguments before calling
+// and build Ruby results after it returns. No unblocking function is passed,
+// so Thread#raise/kill (and Timeout) are delivered only once the call returns:
+// rb_nogvl then raises the pending interrupt by longjmp. That is caught with
+// rb_protect (magnus::rb_sys::protect), so it never unwinds through Rust
+// frames; any value the native call produced is dropped normally (for `open`,
+// the Database is closed) and the exception comes back as `Err`.
+
+use std::ffi::c_void;
+use std::panic::{self, AssertUnwindSafe};
+use std::ptr;
+
+use magnus::Error;
+
+// From ruby/thread.h. Rubies that predate it test only the INTR_FAIL (0x1) and
+// UBF_ASYNC_SAFE (0x2) bits and ignore this one (Task 1, F2).
+const RB_NOGVL_OFFLOAD_SAFE: i32 = 0x4;
+
+struct Call<F, R> {
+    f: Option<F>,
+    out: Option<std::thread::Result<R>>,
+}
+
+unsafe extern "C" fn trampoline<F, R>(data: *mut c_void) -> *mut c_void
+where
+    F: FnOnce() -> R,
+{
+    let call = &mut *(data as *mut Call<F, R>);
+    let f = call.f.take().expect("nogvl closure run twice");
+    // Never unwind across the C frame.
+    call.out = Some(panic::catch_unwind(AssertUnwindSafe(f)));
+    ptr::null_mut()
+}
+
+pub fn without_gvl<F, R>(f: F) -> Result<R, Error>
+where
+    F: FnOnce() -> R + Send,
+    R: Send,
+{
+    let mut call = Call { f: Some(f), out: None };
+    let protected = magnus::rb_sys::protect(|| {
+        unsafe {
+            rb_sys::rb_nogvl(
+                Some(trampoline::<F, R>),
+                &mut call as *mut Call<F, R> as *mut c_void,
+                None,
+                ptr::null_mut(),
+                RB_NOGVL_OFFLOAD_SAFE,
+            );
+        }
+        0 // Qfalse; the value is unused
+    });
+    // On Err, `call` (and anything the closure produced) drops here normally.
+    protected?;
+    match call.out.expect("rb_nogvl returned without running the closure") {
+        Ok(r) => Ok(r),
+        Err(payload) => panic::resume_unwind(payload),
+    }
+}

data/lib/beagle/turso/errors.rb

@@ -0,0 +1,19 @@
+module Beagle
+  module Turso
+    # Base class for every error the native driver raises. A RuntimeError so
+    # code written against 0.1.x, which raised bare RuntimeErrors, still rescues.
+    class Error < RuntimeError; end
+
+    class OpenError < Error; end
+    class ConnectError < Error; end
+    class QueryError < Error; end
+    class SyncError < Error; end
+    # push/pull on a database opened without remote_url:/auth_token:.
+    class NotSyncedError < Error; end
+    # The engine reported the database busy (another session or process holds it).
+    class BusyError < Error; end
+    class ClosedError < Error; end
+    # A handle opened in a parent process was used after fork; open a new one.
+    class ForkedError < Error; end
+  end
+end

data/lib/beagle/turso/version.rb

@@ -1,5 +1,5 @@
 module Beagle
   module Turso
-    VERSION = "0.1.3"
+    VERSION = "0.2.0"
   end
 end

data/lib/beagle/turso.rb

@@ -1,4 +1,5 @@
 require_relative "turso/version"
+require_relative "turso/errors"
 
 # Load the native extension. Precompiled ("fat") gems ship the .so under a
 # per-Ruby-ABI subdir (lib/beagle_turso/<major.minor>/beagle_turso.so); a

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: beagle-turso
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - BeagleSoftwareUK
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -40,8 +40,11 @@ files:
 - README.md
 - ext/beagle_turso/Cargo.toml
 - ext/beagle_turso/extconf.rb
+- ext/beagle_turso/src/errors.rs
 - ext/beagle_turso/src/lib.rs
+- ext/beagle_turso/src/nogvl.rs
 - lib/beagle/turso.rb
+- lib/beagle/turso/errors.rb
 - lib/beagle/turso/version.rb
 homepage: https://github.com/BeagleSoftwareUK/beagle-turso
 licenses: