beagle-turso 0.1.3-aarch64-linux → 0.2.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c85e31d72fe11ab6eb70dc416b1fa4b3782e541955746f4290a7009c3443868
-  data.tar.gz: 199dd3f0118dcde3a7ca0455ef48e21aed47e1e207eb3821868b6be9a04f57a3
+  metadata.gz: 74f1d9beadf880cf80dc6f87f86fca245cbb9fb079948a02bd06fd7678655d08
+  data.tar.gz: 4bfdf6b3a4df383494f4deeb2df0acbfbf1f72053e8fe5ca72ec3cf4a6daab31
 SHA512:
-  metadata.gz: aa4f7a9c455413d71e5bd7ebd635314de450f3a5ae2a6c88b5fd7adcf3cb149a627337855a3b517589f99b9c8399acd3b5738b5f7191aa0c594168379a512500
-  data.tar.gz: 631490722ccb8880afe922e511153a693710f8fa6250e3ddf9e21f09c155e03db7b6551616742e7bda1e93b7db8482f1dc8aa3a0adba651898d7bb88bc71a9c0
+  metadata.gz: e02e2aeaa8b306412f3f0a3b9ac6513906268bd5832cccf64a0e607e7615329f41cad314e9e8f3de611b4e194cd06a8a5895a3291d8c8b83fd4136bb94f9222c
+  data.tar.gz: ee9b8f7141a2aa0519c499bf220c560460565ac16a1de9c126ec6e64972a21eb957a9836750fae54cff520725a1fa51b54131366138bd3ff00698549987b3912

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/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

data/lib/beagle_turso/3.3/beagle_turso.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/beagle_turso/3.3/beagle_turso.so
-size: 33948440 bytes
-sha256: 4e3148bc3815a445f488d3bd1afc1cb91050b2cfc71154dc868145efc652b5f2
+size: 36921384 bytes
+sha256: 3c379ba925a07c255667fc8e7c9a302b7f673b2e7e3df555714d6012952854e9

data/lib/beagle_turso/3.4/beagle_turso.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/beagle_turso/3.4/beagle_turso.so
-size: 33959928 bytes
-sha256: e2e827d0c6af79868e9f9ae1a4371289ecffa4e59ea4fc9ba37652cb2632ec67
+size: 36936560 bytes
+sha256: e895dfcd90349655853f6578437ca109a18fb6f5154b6cfdac5cf3f3d9c5e822

data/lib/beagle_turso/4.0/beagle_turso.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/beagle_turso/4.0/beagle_turso.so
-size: 33964040 bytes
-sha256: f7decb8dfd30f52e2a849920478513e5d45b295c9c1ed46f2ef48b797e0712ab
+size: 36936552 bytes
+sha256: 9e83259ad535e81fdb327cf808b00d7449da653bcd35a4a1c92d34a585774934

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: aarch64-linux
 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: []
 description: |
   A Ruby driver for Turso's database engine, backed by a native Rust
@@ -24,6 +24,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/beagle/turso.rb
+- lib/beagle/turso/errors.rb
 - lib/beagle/turso/version.rb
 - lib/beagle_turso/3.3/beagle_turso.so
 - lib/beagle_turso/3.4/beagle_turso.so