honker 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d4ec2fd1faf6bbe935f087e8b6bcc28e875ee35c5c1212106d4d6fcf4e4eb70
-  data.tar.gz: fbec7fc3f448934b848f2aa4af73c257aacb2dbb6e2bfc1ce9a04944b2b5cff1
+  metadata.gz: c0cbbc6a6ec693c1d719be5d556d216d19bf1f975c42d8ccdf599337117d052d
+  data.tar.gz: 8c2af61f7af5c590057d12bddbe73c99050b818afaab961301b2c0b91f1f7fe7
 SHA512:
-  metadata.gz: 8c20783f45f36b00c477c656843aa786b062990bc7b419034005a039dfce70705142716dda245168d3027e5f51e0c74091ce4bdaa9d3afb577745f999d9ee373
-  data.tar.gz: 75dd17ed09ca7ee424cf145f64a6d94abedfa960b6864001b6a7ef29cee2cd2e0338cc9a67abfe491dc36b83bbf913f6b26468ecfc07aaf54a93e18e8f8aa725
+  metadata.gz: a07431eb49bb65c4ead35b9ab4b5d5259b7d766b77a20be36b6d8ed6f2da6f9280adc687b56e2624954a3a5ac4a58b7a6d2f9117205abfd09d0c78730d31b2a2
+  data.tar.gz: 84e314eda52d30700270a83c5ca8b32956a7ab78f8bce427303562c1186d938dd7802148a2cf9e32f5e57e2e40a530d535e6af89c838d35007fc1b0c3198189b

data/ext/honker/honker-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "honker-core"
-version = "0.2.3"
+version = "0.2.4"
 edition = "2024"
 description = "Shared Rust foundation for Honker bindings (SQLite loadable extension, PyO3, napi-rs, and friends). Not intended for direct use."
 license = "MIT OR Apache-2.0"

data/ext/honker/honker-core/src/honker_ops.rs

@@ -990,24 +990,14 @@ pub fn rate_limit_try(
         rusqlite::params![per],
         |r| r.get(0),
     )?;
-    let current: i64 = conn
-        .query_row(
-            "SELECT COALESCE(MAX(count), 0) FROM _honker_rate_limits
-             WHERE name = ?1 AND window_start = ?2",
-            rusqlite::params![name, window_start],
-            |r| r.get(0),
-        )
-        .unwrap_or(0);
-    if current >= limit {
-        return Ok(0);
-    }
-    conn.execute(
+    let changed = conn.execute(
         "INSERT INTO _honker_rate_limits (name, window_start, count)
          VALUES (?1, ?2, 1)
-         ON CONFLICT(name, window_start) DO UPDATE SET count = count + 1",
-        rusqlite::params![name, window_start],
+         ON CONFLICT(name, window_start) DO UPDATE SET count = count + 1
+         WHERE count < ?3",
+        rusqlite::params![name, window_start, limit],
     )?;
-    Ok(1)
+    Ok(if changed > 0 { 1 } else { 0 })
 }
 
 pub fn rate_limit_sweep(conn: &Connection, older_than_s: i64) -> rusqlite::Result<i64> {
@@ -1269,10 +1259,8 @@ pub fn scheduler_update(
     if !exists {
         return Ok(0);
     }
-    let any_field = cron_expr.is_some()
-        || payload.is_some()
-        || priority.is_some()
-        || expires_s.is_some();
+    let any_field =
+        cron_expr.is_some() || payload.is_some() || priority.is_some() || expires_s.is_some();
     if !any_field {
         // No fields to change. Don't wake the leader for a no-op.
         return Ok(0);
@@ -1316,8 +1304,10 @@ pub fn scheduler_update(
         Ok(())
     })();
     if result.is_err() {
-        let _ = conn.execute_batch("ROLLBACK TO SAVEPOINT honker_sched_update; \
-                                    RELEASE SAVEPOINT honker_sched_update");
+        let _ = conn.execute_batch(
+            "ROLLBACK TO SAVEPOINT honker_sched_update; \
+                                    RELEASE SAVEPOINT honker_sched_update",
+        );
         result?;
     }
     conn.execute_batch("RELEASE SAVEPOINT honker_sched_update")?;

data/ext/honker/honker-core/src/lib.rs

@@ -24,7 +24,7 @@
 //!     acquire, non-blocking try_acquire, and release.
 //!   - [`Readers`] — bounded pool of reader connections that open
 //!     lazily up to a max.
-//!   - [`UpdateWatcher`] — 1 ms PRAGMA-polling thread that fires a
+//!   - [`UpdateWatcher`] — PRAGMA-polling thread that fires a
 //!     callback on every database commit. Uses `PRAGMA data_version`
 //!     for precise change detection, with a periodic stat identity check
 //!     to detect file replacement. Bindings wrap this to surface wake
@@ -59,13 +59,13 @@ use std::time::{Duration, Instant};
 
 /// Which backend drives the update-detection loop.
 ///
-/// `Polling` is the default: 1 ms `PRAGMA data_version` loop, proven
+/// `Polling` is the default: `PRAGMA data_version` loop, proven
 /// correct across all platforms. The optional backends are **experimental**
 /// — they must first prove equivalence to the polling path before
 /// being relied on for correctness.
 #[derive(Debug, Clone, Default)]
 pub enum WatcherBackend {
-    /// Default: 1 ms `PRAGMA data_version` polling loop.
+    /// Default: `PRAGMA data_version` polling loop.
     #[default]
     Polling,
     /// OS kernel filesystem notifications (experimental).
@@ -89,11 +89,40 @@ pub enum WatcherBackend {
     ShmFastPath,
 }
 
+pub const DEFAULT_WATCHER_POLL_INTERVAL: Duration = Duration::from_millis(1);
+
 /// Configuration passed to [`UpdateWatcher::spawn_with_config`] and
 /// [`SharedUpdateWatcher::new_with_config`].
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
 pub struct WatcherConfig {
     pub backend: WatcherBackend,
+    pub poll_interval: Duration,
+}
+
+impl Default for WatcherConfig {
+    fn default() -> Self {
+        Self {
+            backend: WatcherBackend::default(),
+            poll_interval: DEFAULT_WATCHER_POLL_INTERVAL,
+        }
+    }
+}
+
+impl WatcherConfig {
+    pub fn with_backend(backend: WatcherBackend) -> Self {
+        Self {
+            backend,
+            ..Self::default()
+        }
+    }
+
+    pub fn with_poll_interval(mut self, poll_interval: Duration) -> Result<Self, String> {
+        if poll_interval.is_zero() {
+            return Err("watcher poll interval must be positive".to_string());
+        }
+        self.poll_interval = poll_interval;
+        Ok(self)
+    }
 }
 
 impl WatcherBackend {
@@ -680,9 +709,9 @@ fn is_transient_lock_error(e: &rusqlite::Error) -> bool {
 ///
 /// Three-layer defensive architecture:
 ///
-/// 1. **Fast path (every 1 ms):** `PRAGMA data_version`. Compare the
+/// 1. **Fast path:** `PRAGMA data_version`. Compare the
 ///    integer to last seen value. Notify on change. (~3.5 µs/call.)
-/// 2. **Error recovery (every 1 ms on failure):** If the query fails,
+/// 2. **Error recovery:** If the query fails,
 ///    reconnect the SQLite connection and force one wake.
 /// 3. **Identity check (about every 100 ms):** `stat(db_path)` to compare
 ///    `(dev, ino)`. If the file was replaced, panic with a clear
@@ -692,6 +721,7 @@ pub(crate) fn run_poll_loop<F>(
     on_change: F,
     stop: Arc<AtomicBool>,
     ready: std::sync::mpsc::SyncSender<()>,
+    poll_interval: Duration,
 ) where
     F: Fn(),
 {
@@ -724,7 +754,7 @@ pub(crate) fn run_poll_loop<F>(
     drop(ready);
 
     while !stop.load(Ordering::Acquire) {
-        std::thread::sleep(Duration::from_millis(1));
+        std::thread::sleep(poll_interval);
 
         // Path 1: PRAGMA data_version (fast path)
         if let Some(ref c) = conn {
@@ -836,7 +866,9 @@ impl UpdateWatcher {
         let handle = std::thread::Builder::new()
             .name("honker-update-poll".into())
             .spawn(move || match config.backend {
-                WatcherBackend::Polling => run_poll_loop(db_path, on_change, stop_t, ready_tx),
+                WatcherBackend::Polling => {
+                    run_poll_loop(db_path, on_change, stop_t, ready_tx, config.poll_interval)
+                }
                 #[cfg(feature = "kernel-watcher")]
                 WatcherBackend::KernelWatch => {
                     kernel_watcher::run_kernel_watch_loop(db_path, on_change, stop_t, ready_tx);
@@ -2329,6 +2361,7 @@ while True:
             },
             WatcherConfig {
                 backend: WatcherBackend::KernelWatch,
+                ..WatcherConfig::default()
             },
         );
 
@@ -2407,6 +2440,7 @@ while True:
             },
             WatcherConfig {
                 backend: WatcherBackend::ShmFastPath,
+                ..WatcherConfig::default()
             },
         );
 
@@ -2487,7 +2521,7 @@ while True:
             move || {
                 count_t.fetch_add(1, AO::Relaxed);
             },
-            WatcherConfig { backend },
+            WatcherConfig::with_backend(backend),
         );
 
         // Drain init wakes (covers shm + kernel setup) before baseline.
@@ -2704,7 +2738,7 @@ while True:
                     .expect("wake_times mutex poisoned")
                     .push(std::time::Instant::now());
             },
-            WatcherConfig { backend },
+            WatcherConfig::with_backend(backend),
         );
 
         // Drain initialization wakes.
@@ -2768,7 +2802,10 @@ while True:
         ignore = "notify/kqueue can drop the watcher thread under CI load; functional kernel watcher tests still run"
     )]
     #[cfg(feature = "kernel-watcher")]
-    #[cfg_attr(target_os = "macos", ignore = "kqueue under CI load may deliver zero wakes")]
+    #[cfg_attr(
+        target_os = "macos",
+        ignore = "kqueue under CI load may deliver zero wakes"
+    )]
     fn kernel_watcher_wake_latency_is_event_driven() {
         let tmp = std::env::temp_dir().join(format!(
             "honker-kw-lat-{}-{}",
@@ -2872,6 +2909,7 @@ while True:
             || {},
             WatcherConfig {
                 backend: WatcherBackend::KernelWatch,
+                ..WatcherConfig::default()
             },
         );
 
@@ -2931,6 +2969,14 @@ while True:
         ));
     }
 
+    #[test]
+    fn watcher_config_rejects_zero_poll_interval() {
+        let err = WatcherConfig::default()
+            .with_poll_interval(Duration::from_millis(0))
+            .unwrap_err();
+        assert_eq!(err, "watcher poll interval must be positive");
+    }
+
     #[test]
     #[cfg(not(feature = "kernel-watcher"))]
     fn watcher_backend_parse_rejects_uncompiled_kernel() {
@@ -3062,8 +3108,11 @@ while True:
             f.write_all(&buf).unwrap();
         }
 
-        let watcher =
-            UpdateWatcher::spawn_with_config(tmp.clone(), || {}, WatcherConfig { backend });
+        let watcher = UpdateWatcher::spawn_with_config(
+            tmp.clone(),
+            || {},
+            WatcherConfig::with_backend(backend),
+        );
         // Generous initial wait so the watcher has snapshotted the
         // initial inode under CI scheduling pressure.
         std::thread::sleep(Duration::from_millis(300));

data/ext/honker/honker-extension/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "honker-extension"
-version = "0.2.3"
+version = "0.2.4"
 edition = "2024"
 description = "SQLite loadable extension for Honker. Adds honker_* SQL functions (queues, streams, scheduler, pub/sub) to any SQLite client."
 license = "MIT OR Apache-2.0"
@@ -23,7 +23,7 @@ crate-type = ["cdylib"]
 # Using both `path` and `version` lets Cargo publish this crate to
 # crates.io referencing the real honker-core = "0.2" while still
 # using the in-tree source for local builds.
-honker-core = { path = "../honker-core", version = "0.2.3", default-features = false }
+honker-core = { path = "../honker-core", version = "0.2.4", default-features = false }
 # "loadable_extension" feature makes rusqlite usable from inside a
 # sqlite3_extension_init entry point.
 rusqlite = { version = "0.39.0", features = ["functions", "hooks", "loadable_extension"] }

data/ext/honker/honker-extension/src/lib.rs

@@ -69,12 +69,17 @@ static NEXT_SQL_WATCHER_ID: AtomicU64 = AtomicU64::new(1);
 fn open_watcher_handle(
     db_path: &str,
     backend: Option<&str>,
+    watcher_poll_interval_ms: Option<u64>,
 ) -> std::result::Result<HonkerWatcherHandle, String> {
     let backend = honker_core::WatcherBackend::parse(backend.filter(|s| !s.is_empty()))?;
     backend.probe(PathBuf::from(db_path).as_path())?;
+    let mut config = honker_core::WatcherConfig::with_backend(backend);
+    if let Some(ms) = watcher_poll_interval_ms {
+        config = config.with_poll_interval(Duration::from_millis(ms))?;
+    }
     let shared = Arc::new(honker_core::SharedUpdateWatcher::new_with_config(
         PathBuf::from(db_path),
-        honker_core::WatcherConfig { backend },
+        config,
     ));
     let (sub_id, rx) = shared.subscribe();
     Ok(HonkerWatcherHandle { shared, sub_id, rx })
@@ -88,7 +93,7 @@ fn attach_watcher_sql_functions(conn: &Connection) -> Result<()> {
         |ctx| {
             let db_path: String = ctx.get(0)?;
             let backend: Option<String> = ctx.get(1)?;
-            let handle = open_watcher_handle(&db_path, backend.as_deref()).map_err(|e| {
+            let handle = open_watcher_handle(&db_path, backend.as_deref(), None).map_err(|e| {
                 rusqlite::Error::UserFunctionError(Box::new(std::io::Error::other(e)))
             })?;
             let id = NEXT_SQL_WATCHER_ID.fetch_add(1, Ordering::Relaxed);
@@ -96,6 +101,24 @@ fn attach_watcher_sql_functions(conn: &Connection) -> Result<()> {
             Ok(id as i64)
         },
     )?;
+    conn.create_scalar_function(
+        "honker_update_watcher_open",
+        3,
+        FunctionFlags::SQLITE_UTF8,
+        |ctx| {
+            let db_path: String = ctx.get(0)?;
+            let backend: Option<String> = ctx.get(1)?;
+            let poll_interval_ms: Option<i64> = ctx.get(2)?;
+            let poll_interval_ms = poll_interval_ms.map(|ms| ms.max(0) as u64);
+            let handle = open_watcher_handle(&db_path, backend.as_deref(), poll_interval_ms)
+                .map_err(|e| {
+                    rusqlite::Error::UserFunctionError(Box::new(std::io::Error::other(e)))
+                })?;
+            let id = NEXT_SQL_WATCHER_ID.fetch_add(1, Ordering::Relaxed);
+            SQL_WATCHERS.lock().unwrap().insert(id, handle);
+            Ok(id as i64)
+        },
+    )?;
     conn.create_scalar_function(
         "honker_update_watcher_wait",
         2,
@@ -266,7 +289,46 @@ pub unsafe extern "C" fn honker_watcher_open(
             .to_str()
             .map_err(|e| format!("invalid db_path UTF-8: {e}"))?;
         let backend = unsafe { cstr_to_string(backend) }?;
-        let handle = open_watcher_handle(path, backend.as_deref())?;
+        let handle = open_watcher_handle(path, backend.as_deref(), None)?;
+        Ok(Box::into_raw(Box::new(handle)))
+    })) {
+        Ok(Ok(ptr)) => ptr,
+        Ok(Err(err)) => {
+            unsafe { write_error(err_buf, err_buf_len, &err) };
+            ptr::null_mut()
+        }
+        Err(payload) => {
+            let err = panic_error(payload).to_string();
+            unsafe { write_error(err_buf, err_buf_len, &err) };
+            ptr::null_mut()
+        }
+    }
+}
+
+/// Open a core-backed update watcher over `db_path` with options.
+///
+/// `watcher_poll_interval_ms` must be positive. Use `honker_watcher_open`
+/// for the default 1 ms cadence.
+///
+/// # Safety
+/// All pointers must be valid NUL-terminated strings when non-null.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn honker_watcher_open_v2(
+    db_path: *const c_char,
+    backend: *const c_char,
+    watcher_poll_interval_ms: u64,
+    err_buf: *mut c_char,
+    err_buf_len: usize,
+) -> *mut HonkerWatcherHandle {
+    match catch_unwind(AssertUnwindSafe(|| {
+        if db_path.is_null() {
+            return Err("db_path is null".to_string());
+        }
+        let path = unsafe { CStr::from_ptr(db_path) }
+            .to_str()
+            .map_err(|e| format!("invalid db_path UTF-8: {e}"))?;
+        let backend = unsafe { cstr_to_string(backend) }?;
+        let handle = open_watcher_handle(path, backend.as_deref(), Some(watcher_poll_interval_ms))?;
         Ok(Box::into_raw(Box::new(handle)))
     })) {
         Ok(Ok(ptr)) => ptr,

data/lib/honker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Honker
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/honker.rb

@@ -113,11 +113,11 @@ module Honker
   end
 
   class CoreWatcher
-    def initialize(db_path, extension_path, backend)
+    def initialize(db_path, extension_path, backend, watcher_poll_interval_ms)
       @lib = Fiddle.dlopen(extension_path)
       @open = Fiddle::Function.new(
-        @lib["honker_watcher_open"],
-        [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T],
+        @lib["honker_watcher_open_v2"],
+        [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T],
         Fiddle::TYPE_VOIDP,
       )
       @wait = Fiddle::Function.new(
@@ -131,7 +131,13 @@ module Honker
         Fiddle::TYPE_VOID,
       )
       err = "\0" * 1024
-      @handle = @open.call(db_path.to_s, backend.to_s, err, err.bytesize)
+      @handle = @open.call(
+        db_path.to_s,
+        backend.to_s,
+        watcher_poll_interval_ms || 1,
+        err,
+        err.bytesize,
+      )
       return unless @handle.to_i.zero?
 
       raise ArgumentError, err.delete_suffix("\0").split("\0", 2).first
@@ -171,10 +177,14 @@ module Honker
     attr_reader :db
 
     def initialize(path, extension_path: nil, watcher_backend: nil,
+                   watcher_poll_interval_ms: nil,
                    extension_resolver: ExtensionResolver.new)
       unless watcher_backend.nil? || watcher_backend.is_a?(String)
         raise ArgumentError, "unknown watcher backend"
       end
+      unless watcher_poll_interval_ms.nil? || watcher_poll_interval_ms.to_i.positive?
+        raise ArgumentError, "watcher_poll_interval_ms must be positive"
+      end
 
       resolved_extension = extension_resolver.resolve(extension_path)
       @db = SQLite3::Database.new(path)
@@ -186,7 +196,7 @@ module Honker
       @db.enable_load_extension(false)
       @db.execute_batch(DEFAULT_PRAGMAS)
       @db.execute("SELECT honker_bootstrap()")
-      @watcher = CoreWatcher.new(path, resolved_extension, watcher_backend)
+      @watcher = CoreWatcher.new(path, resolved_extension, watcher_backend, watcher_poll_interval_ms)
     end
 
     def close

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: honker
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Russell Romney