beagle-turso 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f35de8fc3b33e04d7d170ee1032ee2d57af85642fcec1b120d591700baa9532c
-  data.tar.gz: 67bbe8aaa50468fb2cf0ef2c44e208fd414c4dff3694e9ae2a8dc8394ae671b7
+  metadata.gz: f49be5566a3b64416bccffc8c792e167e770139827016890070836eac6ab2484
+  data.tar.gz: c8be2046fb4e78a337008dcdd488f5b8587d754c77692d73e15f90dc0e3d2f8b
 SHA512:
-  metadata.gz: ce2cef361285eed71718e587fbbe3a1a3d321e2e45ba269b1274edbbc622d073a0b55274ea2950e89e67eafeaceb70a0f3e469e0bd0bf29b59ac2ffedc205095
-  data.tar.gz: edd3d0df3ce5ba628e4ca6923c9df228c9f480d9a05ba4bf879f95a599adeed5d362f38f10b8621ee1d0fa01a0ca07ae1a69e9b85065c0fd089b59e3510706be
+  metadata.gz: 591b0e8a2e9e71d767008bac9a2742a2c93e4bb74424f586d2af035339aa1510c6fb883e770b20440a9ad561b5c88e9b113f63f8b4b506355e18f4e39442ee23
+  data.tar.gz: 53782d7a3a82cffb627bdbc107ab022619cae5fe49a7fdc85d233aa04910497da7932de863b384d14199d77f63d35473021bf5adc8d95d5d97c13b00355d3145

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,120 @@ 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.
+
+## Background sync
+
+`Beagle::Turso::Syncer` keeps the remote copy current without a job system:
+
+```ruby
+db = Beagle::Turso::Database.open(local_path: "app.db", remote_url: url, auth_token: token)
+
+syncer = Beagle::Turso::Syncer.new(
+  db,
+  interval: 30,        # seconds between cycles
+  pull: true,          # pull after each push (false = push only)
+  max_backoff: 300,    # retry delay cap, seconds
+  on_error: ->(error, status) { ErrorTracker.notify(error) },
+  logger: Logger.new($stderr),
+).start
+
+syncer.status   # => #<data Status running=true, syncing=false, last_push_at=..., ...>
+syncer.sync_now # one cycle now, on this thread; :ok, or :busy if one is running
+                # (a failure is recorded, passed to on_error, then re-raised)
+
+# on shutdown, before closing the database:
+syncer.stop(timeout: 10)   # waits for an in-flight sync, then pushes once more
+# syncer.stop(timeout: 10, final_push: false)  # waits, but doesn't push again
+db.close
+```
+
+- **Opt-in.** Requiring the gem starts nothing. `start` runs one background
+  thread. `push` and `pull` release the GVL, so that thread doesn't hold up
+  requests on other threads or a Falcon reactor.
+- **Failures don't stop it.** Each failure is logged (at `warn`) and passed to
+  `on_error`. The next attempt waits `interval × 2ⁿ`, capped at
+  `max_backoff`, with ±20% jitter. A success resets the count. A failed push
+  skips that cycle's pull. A logger or `on_error` that raises a
+  `StandardError` is ignored (an `on_error` error is logged).
+- **`sync_now` re-raises.** A failed `sync_now` records the failure in
+  `status`, logs it, calls `on_error`, then raises the error to you. Since
+  `on_error` has already seen it, don't report it again from a `rescue`. If
+  the error message carried a URL or credential, both `on_error` and the
+  caller get a copy of the error (same class and backtrace) with the redacted
+  message.
+- **Status is for monitoring, not lag.** `last_push_at` says when a push last
+  succeeded, not how much is still unpushed. Alert when `consecutive_failures`
+  grows, or when `last_push_at` gets older than you can tolerate. The site keeps
+  serving from the local replica either way. `destination` is the remote host
+  only, and error messages are stripped of URLs and tokens.
+- **Shutdown is best-effort.** `stop(timeout:, final_push: true)` stops the
+  loop, waits for a cycle in flight on any thread (the loop or a concurrent
+  `sync_now`), then pushes once more unless `final_push: false`. It waits up
+  to `timeout` seconds in total. A push or pull already in flight can't be
+  interrupted, so if the deadline passes, `stop` returns with
+  `status.syncing == true` and the work finishes in the background; process
+  exit then waits for that native call to return (until your platform's kill
+  timeout). `stop(timeout: 0)` skips the final push. Called from inside
+  `on_error`, `stop` can't wait for the cycle it is part of, so it returns
+  without a final push. If the network is down, the deadline passes, or the
+  process is killed, writes stay local until the next process pushes them.
+  `stop` never closes the database; do that after it returns.
+- **Don't call `stop` from a signal handler.** Inside `Signal.trap` it raises
+  `ThreadError` (it takes locks). Call it from your server's shutdown hook or
+  `at_exit`.
+- **One syncer per process, created after fork.** A stopped syncer can't be
+  restarted, so create a new one. With Puma in single mode, create it in an
+  initializer or `on_booted`; in cluster mode, create it in `on_worker_boot`
+  (each worker gets its own) and call `stop` from `on_worker_shutdown` or
+  `at_exit`.
+
 ## 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/redaction.rb

@@ -0,0 +1,41 @@
+require "uri"
+
+module Beagle
+  module Turso
+    # Strips credentials from text before it reaches a log, a status or a
+    # callback. Engine error messages can embed the remote URL; the auth token
+    # itself is sent as a header, but a URL can still carry userinfo or a
+    # token query parameter, so reduce every URL to scheme://host.
+    module Redaction
+      # scheme://[userinfo@]host[...]: keep scheme and host (a bracketed IPv6
+      # literal included), drop userinfo, port, path, query and fragment. The
+      # scheme length is bounded so a long run of "a.a.a." stays linear.
+      URL = %r{\b([a-z][a-z0-9+.-]{0,31})://(?:[^/\s?#"'@\[]+@)?(\[[0-9a-f:.]*\]|[^/\s?#"':\[]+)[^\s"']*}i
+      # Authorization schemes: keep the scheme word, blank the credential.
+      AUTH_SCHEME = /\b(Bearer|Basic)\s+[^\s"',;]+/i
+      # key=value / key: value / "key": "value" / key%3Dvalue, where the key is
+      # a whole word ending in a secret-ish name (turso_auth_token, x-api-key,
+      # access_token, ...). The lookbehind pins the key to a word start, which
+      # keeps the unbounded prefix linear.
+      SECRET_PARAM = /(?<![\w-])([\w-]*?(?:auth_?token|token|jwt|api[_-]?key|password|passwd|secret|authorization))(["']?\s*(?:[=:]|%3D)\s*["']?)(?!(?:Bearer|Basic)\s)[^\s"'&,;]+/i
+      # A bare JWT (header.payload.signature, base64url).
+      JWT = /\beyJ[\w-]+\.[\w-]+\.[\w-]+/
+
+      module_function
+
+      def message(text)
+        text.to_s
+          .gsub(URL) { "#{Regexp.last_match(1)}://#{Regexp.last_match(2)}" }
+          .gsub(JWT, "[redacted]")
+          .gsub(AUTH_SCHEME, '\1 [redacted]')
+          .gsub(SECRET_PARAM) { "#{Regexp.last_match(1)}#{Regexp.last_match(2)}[redacted]" }
+      end
+
+      def host(url)
+        URI.parse(url.to_s).host
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end

data/lib/beagle/turso/syncer.rb

@@ -0,0 +1,293 @@
+module Beagle
+  module Turso
+    # Keeps a synced Database's remote copy current: runs push (then pull) on
+    # a background thread, backs off on failure, reports status, and pushes
+    # one last time on stop. Framework-neutral and opt-in: nothing runs until
+    # #start, and it never closes the database (its owner does, after #stop).
+    #
+    # push/pull release the GVL (see the README), so the syncer's thread does
+    # not stall other Ruby threads or a fiber scheduler's reactor.
+    class Syncer
+      Status = Data.define(
+        :running, :syncing,
+        :last_push_at, :last_pull_at,
+        :last_error_class, :last_error_message, :last_error_at,
+        :consecutive_failures, :destination
+      )
+
+      # Retry delays are spread by ±JITTER so restarted processes don't retry
+      # in lockstep.
+      JITTER = 0.2
+
+      # Backoff stops growing past interval * 2**MAX_EXPONENT (max_backoff
+      # caps it long before), so a long outage never builds a bignum.
+      MAX_EXPONENT = 32
+
+      # How often a final push polls for an in-flight cycle to finish.
+      LOCK_POLL = 0.005
+
+      def initialize(database, interval: 30, pull: true, max_backoff: 300, on_error: nil, logger: nil, random: Random.new)
+        unless database.synced?
+          raise NotSyncedError, "Syncer needs a synced database (opened with remote_url: and auth_token:)"
+        end
+        raise ArgumentError, "interval must be positive" unless interval.positive?
+        raise ArgumentError, "max_backoff must be at least interval" if max_backoff < interval
+
+        @database = database
+        @interval = interval
+        @pull = pull
+        @max_backoff = max_backoff
+        @on_error = on_error
+        @logger = logger
+        @random = random
+
+        @cycle_lock = Mutex.new # held for the whole of one push/pull cycle
+        @state_lock = Mutex.new # guards the fields below and the wake-up signal
+        @wake = ConditionVariable.new
+        @thread = nil
+        @stopping = false
+        @stopped = false
+        @syncing = false
+        @last_push_at = nil
+        @last_pull_at = nil
+        @last_error_class = nil
+        @last_error_message = nil
+        @last_error_at = nil
+        @consecutive_failures = 0
+      end
+
+      # Runs one cycle on the calling thread. Returns :ok, or :busy (without
+      # waiting) when another cycle is in progress. A failure is recorded in
+      # #status, reported to on_error/logger, then re-raised. If the message
+      # carried credentials, both on_error and the caller get a copy of the
+      # error (same class and backtrace) with the redacted message instead.
+      def sync_now
+        cycle(pull: @pull)
+      end
+
+      def status
+        @state_lock.synchronize do
+          Status.new(
+            running: loop_running?,
+            syncing: @syncing,
+            last_push_at: @last_push_at,
+            last_pull_at: @last_pull_at,
+            last_error_class: @last_error_class,
+            last_error_message: @last_error_message,
+            last_error_at: @last_error_at,
+            consecutive_failures: @consecutive_failures,
+            destination: @database.remote_host
+          )
+        end
+      end
+
+      # Starts the background thread. Idempotent while running. A stopped
+      # syncer cannot be restarted; create a new one.
+      def start
+        @state_lock.synchronize do
+          raise Error, "syncer has been stopped; create a new one" if @stopped
+          return self if @thread
+
+          @thread = Thread.new { run_loop }
+          @thread.name = "beagle-turso-syncer"
+        end
+        self
+      end
+
+      # True while the background thread is alive and not stopping. A loop
+      # thread that died (e.g. on_error raised a non-StandardError) is not
+      # running.
+      def running?
+        @state_lock.synchronize { loop_running? }
+      end
+
+      # Stops the loop, waits for a cycle in flight on any other thread
+      # (the loop or a concurrent sync_now), then, if final_push and the
+      # deadline allows, pushes once more. Waits at most `timeout` seconds in
+      # total: an in-flight push or pull cannot be interrupted, so if the
+      # deadline passes first this returns anyway with status.syncing true and
+      # the work finishes in the background. Called from inside a cycle (from
+      # on_error), it cannot wait for that cycle and skips the final push.
+      # Never closes the database. Idempotent.
+      def stop(timeout: 10, final_push: true)
+        unless timeout.is_a?(Numeric) && timeout >= 0
+          raise ArgumentError, "timeout must be a non-negative number of seconds"
+        end
+
+        first = @state_lock.synchronize do
+          next false if @stopped
+
+          @stopped = true
+          @stopping = true
+          @wake.broadcast
+          true
+        end
+        return status unless first
+
+        deadline = monotonic_now + timeout
+        # Joining our own thread (stop called from on_error) would raise; that
+        # thread exits by itself once the callback returns.
+        join_quietly(@thread, deadline) if @thread && @thread != Thread.current
+        # Inside a cycle (stop from on_error) this thread holds the cycle lock,
+        # so waiting for it would only burn the deadline.
+        unless @cycle_lock.owned? || loop_alive?
+          if final_push && remaining(deadline).positive?
+            pusher = Thread.new do
+              cycle(pull: false, wait_until: deadline)
+            rescue StandardError
+              nil # already recorded, logged and reported by cycle
+            end
+            join_quietly(pusher, deadline)
+          elsif lock_by(deadline)
+            @cycle_lock.unlock # only waiting for the in-flight cycle
+          end
+        end
+        status
+      end
+
+      private
+
+      def run_loop
+        loop do
+          return if @state_lock.synchronize { @stopping }
+
+          delay =
+            begin
+              cycle(pull: @pull)
+              @interval
+            rescue StandardError
+              retry_delay(@state_lock.synchronize { @consecutive_failures })
+            end
+
+          @state_lock.synchronize do
+            return if @stopping
+
+            @wake.wait(@state_lock, delay)
+          end
+        end
+      end
+
+      def loop_alive?
+        @thread&.alive? && @thread != Thread.current
+      end
+
+      # Caller holds @state_lock.
+      def loop_running?
+        !!@thread&.alive? && !@stopping
+      end
+
+      # Joins a helper thread until the deadline. A thread that died from an
+      # exception re-raises it here; stop must still finish, so log it.
+      def join_quietly(thread, deadline)
+        thread.join(remaining(deadline))
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise if thread.alive? # not the thread's death: e.g. an interrupt aimed at us
+
+        safe_warn("beagle-turso syncer thread died (#{e.class}): #{Redaction.message(e.message)}")
+      end
+
+      # Takes the cycle lock, waiting for an in-flight cycle until the
+      # deadline. False if the deadline passed first.
+      def lock_by(deadline)
+        until @cycle_lock.try_lock
+          left = remaining(deadline)
+          return false unless left.positive?
+
+          sleep([LOCK_POLL, left].min)
+        end
+        true
+      end
+
+      def remaining(deadline)
+        [deadline - monotonic_now, 0].max
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # One push (then pull) under the cycle lock. Without wait_until it never
+      # waits (returns :busy); with it, it waits for the lock until then.
+      def cycle(pull:, wait_until: nil)
+        locked = wait_until ? lock_by(wait_until) : @cycle_lock.try_lock
+        return :busy unless locked
+
+        begin
+          set_syncing(true)
+          @database.push
+          @state_lock.synchronize { @last_push_at = Time.now }
+          if pull
+            @database.pull
+            @state_lock.synchronize { @last_pull_at = Time.now }
+          end
+          @state_lock.synchronize { @consecutive_failures = 0 }
+          :ok
+        rescue StandardError => e
+          reported = record_failure(e)
+          raise e if reported.equal?(e)
+
+          raise reported, cause: nil # the cause would carry the unredacted original
+        ensure
+          begin
+            set_syncing(false)
+          ensure
+            @cycle_lock.unlock
+          end
+        end
+      end
+
+      def set_syncing(value)
+        @state_lock.synchronize { @syncing = value }
+      end
+
+      # Records, logs and reports a failure. Returns the error to hand on:
+      # the original, or a redacted copy if its message carried credentials.
+      def record_failure(error)
+        message = Redaction.message(error.message).freeze
+        @state_lock.synchronize do
+          @consecutive_failures += 1
+          @last_error_class = error.class.to_s
+          @last_error_message = message
+          @last_error_at = Time.now
+        end
+        safe_warn("beagle-turso sync failed (#{error.class}): #{message}")
+        reported = redacted_error(error, message)
+        notify(reported)
+        reported
+      end
+
+      def redacted_error(error, message)
+        return error if message == error.message
+
+        copy = begin
+          error.exception(message)
+        rescue StandardError
+          nil
+        end
+        copy = Error.new(message) unless copy.is_a?(Exception) && copy.message == message
+        copy.set_backtrace(error.backtrace) if copy.backtrace.nil? && error.backtrace
+        copy
+      end
+
+      def notify(error)
+        @on_error&.call(error, status)
+      rescue StandardError => e
+        safe_warn("beagle-turso syncer on_error raised (#{e.class}): #{Redaction.message(e.message)}")
+      end
+
+      # A broken logger must not skip on_error or replace the sync error.
+      def safe_warn(message)
+        @logger&.warn(message)
+      rescue StandardError
+        nil
+      end
+
+      # Delay before the next attempt after `failures` consecutive failures:
+      # interval * 2**failures, capped at max_backoff, then spread by ±JITTER.
+      def retry_delay(failures)
+        base = [@interval * (2**[failures, MAX_EXPONENT].min), @max_backoff].min
+        base * (1 + @random.rand(-JITTER..JITTER))
+      end
+    end
+  end
+end

data/lib/beagle/turso/version.rb

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

data/lib/beagle/turso.rb

@@ -1,4 +1,7 @@
 require_relative "turso/version"
+require_relative "turso/errors"
+require_relative "turso/redaction"
+require_relative "turso/syncer"
 
 # 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
@@ -16,12 +19,28 @@ module Beagle
       # Opens a local-only database, or one synced with a remote Turso
       # database when both `remote_url` and `auth_token` are given (see
       # `#push`/`#pull`). Delegates to the native `_open` primitive, which
-      # takes its arguments positionally.
+      # takes its arguments positionally. Only the remote host is kept on
+      # the Ruby object; the token is never stored.
       def self.open(local_path:, remote_url: nil, auth_token: nil, bootstrap_if_empty: true)
-        _open(local_path, remote_url, auth_token, bootstrap_if_empty)
+        db = _open(local_path, remote_url, auth_token, bootstrap_if_empty)
+        if remote_url && auth_token
+          db.instance_variable_set(:@synced, true)
+          db.instance_variable_set(:@remote_host, Redaction.host(remote_url))
+        end
+        db
       end
 
       private_class_method :_open
+
+      # True when opened with both remote_url: and auth_token:, i.e. when
+      # #push/#pull talk to a remote.
+      def synced?
+        @synced == true
+      end
+
+      # The remote database's host, without scheme, path, query or
+      # credentials; nil for a local-only database.
+      attr_reader :remote_host
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: beagle-turso
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.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,13 @@ 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/redaction.rb
+- lib/beagle/turso/syncer.rb
 - lib/beagle/turso/version.rb
 homepage: https://github.com/BeagleSoftwareUK/beagle-turso
 licenses: