honker 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf6de4cce9d9b068ecf07c59977f5ffea3295bcc55e3dc043033d8855bff648
-  data.tar.gz: 619580c9de45ccadb5ac20b41bea018c2ef5e11759f6d0a837d13c6239b76de4
+  metadata.gz: 41df996d169333da2b22d08dbb613537c16c1d92519e86558986b11737406bda
+  data.tar.gz: c052dd0d545ea520914e650b488138b1512527f1278c3e7c4bf72932c40df055
 SHA512:
-  metadata.gz: 3ac9490e51f9dd4edca01a4a4af3a28ec3603113e2f02bbf54d80784d1d6c6946cc8c6c70d805acb3d1df3e84ec3d9d84ff5076901c07315888e35b1de7a25f1
-  data.tar.gz: db21f18ef6609c2cf330428d2518b21c903fd22dd64ec8156da3ce127ab03188181142d6d5872841e3d690e8ef2cf335a3f7494a2520b9887d3d51de8c0d8801
+  metadata.gz: 414c0d65e26bb76e4a6aad15674b32a448fefc75ca13ad060cc570fa86e5b0180efa5875859e08def6afd0b9c92f9eb42f26d7420478abc7a50d9ec9ab133550
+  data.tar.gz: 78c16c3beea3611f590602f338ec7aa6e5d27edb9a2ffa81b8267c64a835fd129f07562bbbf6c67d6d4fb386421b5a2d965c3a7454c26f21afe76ee7a29ade36

data/README.md

@@ -1,6 +1,11 @@
 # honker (Ruby)
 
-Ruby binding for [Honker](https://honker.dev) — durable queues, streams, pub/sub, and scheduler on SQLite.
+Ruby binding for [Honker](https://github.com/russellromney/honker): durable queues, streams, pub/sub, and time-trigger scheduling on SQLite.
+
+Full docs:
+
+- [Main repo](https://github.com/russellromney/honker)
+- [Docs](https://honker.dev)
 
 ## Install
 
@@ -8,81 +13,41 @@ Ruby binding for [Honker](https://honker.dev) — durable queues, streams, pub/s
 gem "honker"
 ```
 
-You'll also need the Honker SQLite extension (`libhonker.dylib` on macOS, `libhonker.so` on Linux). Prebuilds at [GitHub releases](https://github.com/russellromney/honker/releases/latest), or build:
-
-```bash
-git clone https://github.com/russellromney/honker
-cd honker
-cargo build --release -p honker-extension
-# → target/release/libhonker_extension.{dylib,so}
-```
-
-## Requirements
-
-- Ruby 3.0+
-- `sqlite3` gem ≥ 1.7 (pulled in automatically)
+You also need the Honker SQLite extension from the main repo.
 
 ## Quick start
 
 ```ruby
 require "honker"
 
-db = Honker::Database.new("app.db", extension_path: "./libhonker_extension.dylib")
-q  = db.queue("emails")
+db = Honker::Database.new("app.db", extension_path: "./libhonker_ext.dylib")
+q = db.queue("emails")
 
-# Enqueue (atomic-with-your-write via business transactions; see below)
-q.enqueue({ to: "alice@example.com" })
+q.enqueue({to: "alice@example.com"})
 
-# Claim + process + ack
-job = q.claim_one("worker-1")
-if job
+if (job = q.claim_one("worker-1"))
   send_email(job.payload)
   job.ack
 end
 ```
 
-## API
-
-### `Honker::Database.new(path, extension_path:)`
-
-Opens (or creates) a SQLite database, loads the Honker extension, applies default PRAGMAs, and bootstraps the schema.
-
-### `#queue(name, visibility_timeout_s: 300, max_attempts: 3)`
-
-Handle to a named queue.
-
-### `Queue#enqueue(payload, delay:, run_at:, priority:, expires:)`
-
-Inserts a job. `payload` is any JSON-serializable value. Returns the row id.
+Delayed jobs use `run_at:`:
 
-### `Queue#claim_batch(worker_id, n)` / `Queue#claim_one(worker_id)`
-
-Atomically claim up to N jobs (or 1).
-
-### `Job#ack` / `Job#retry(delay_s:, error:)` / `Job#fail(error:)` / `Job#heartbeat(extend_s:)`
-
-Claim lifecycle. `ack` deletes. `retry` puts back with a delay (or moves to `_honker_dead` if max_attempts reached). `fail` moves to dead unconditionally. `heartbeat` extends the visibility timeout.
-
-### `Database#notify(channel, payload)`
-
-Fire a `pg_notify`-style signal. Returns the notification id.
-
-## What's not here yet
+```ruby
+q.enqueue({to: "later@example.com"}, run_at: Time.now.to_i + 10)
+```
 
-- `listen` / WAL-based async iterator (watcher API — in progress)
-- Streams (durable pub/sub with per-consumer offsets)
-- Scheduler (cron-style periodic tasks)
+Recurring schedules use `schedule:`:
 
-All available via raw SQL on the same database (`db.db.execute("SELECT honker_stream_publish(...)")`). Idiomatic Ruby wrappers coming in a future release.
+```ruby
+sched = db.scheduler
+sched.add(name: "fast", queue: "emails", schedule: "@every 1s", payload: {kind: "tick"})
+```
 
-## Testing
+Supported schedule forms:
 
-```bash
-# Build the extension
-cd /path/to/honker && cargo build --release -p honker-extension
+- `0 3 * * *`
+- `*/2 * * * * *`
+- `@every 1s`
 
-# Run the tests
-cd packages/honker-ruby
-bundle install
-bundle exec rake test     # or: ruby -Ilib -Ispec spec/honker_spec.rb
-```
+`schedule:` is the canonical recurring name. `cron:` still works as a compatibility alias.

data/honker.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.summary       = "Durable queues, streams, pub/sub, and scheduler on SQLite."
   spec.description   = <<~DESC.strip
     Ruby binding for Honker — a SQLite-native task runtime. Queues,
-    streams, pub/sub, cron scheduler, results, locks, rate limits, all
+    streams, pub/sub, time-trigger scheduler, results, locks, rate limits, all
     in one .db file. Thin wrapper around the Honker SQLite loadable
     extension; no Redis, no external broker.
   DESC

data/lib/honker/scheduler.rb

@@ -10,7 +10,7 @@ module Honker
     end
   end
 
-  # Cron-style scheduler. Register tasks with `add`; `tick` fires all
+  # Time-trigger scheduler. Register tasks with `add`; `tick` fires all
   # boundaries that have elapsed since the last tick and enqueues the
   # resulting jobs. `run(owner:, stop:)` drives the loop under a
   # leader-elected advisory lock.
@@ -28,18 +28,30 @@ module Honker
     # write; too large and a standby waits longer than necessary after
     # a crash. Matches the Rust binding.
     HEARTBEAT_S = 20
+    UPDATE_POLL_S = 0.05
 
     def initialize(db)
       @db = db
     end
 
-    # Register a cron-scheduled task. Idempotent by `name`; registering
-    # the same name twice replaces the previous row.
-    def add(name:, queue:, cron:, payload:, priority: 0, expires_s: nil)
+    # Register a scheduled task. `cron:` is kept for backward
+    # compatibility; `schedule:` is the clearer name and can hold:
+    #
+    # - 5-field cron
+    # - 6-field cron
+    # - `@every <n><unit>` like `@every 1s`
+    #
+    # Idempotent by `name`; registering the same name twice replaces
+    # the previous row.
+    def add(name:, queue:, cron: nil, schedule: nil, payload:, priority: 0, expires_s: nil)
+      expr = schedule || cron
+      raise ArgumentError, "must provide cron: or schedule:" if expr.nil? || expr.empty?
+
       @db.db.get_first_row(
         "SELECT honker_scheduler_register(?, ?, ?, ?, ?, ?)",
-        [name, queue, cron, JSON.dump(payload), priority, expires_s],
+        [name, queue, expr, JSON.dump(payload), priority, expires_s],
       )
+      @db.mark_updated
       nil
     end
 
@@ -49,7 +61,7 @@ module Honker
       @db.db.get_first_row(
         "SELECT honker_scheduler_unregister(?)",
         [name],
-      )[0]
+      )[0].tap { @db.mark_updated }
     end
 
     # Fire all due boundaries at `now`. Returns an array of
@@ -86,7 +98,7 @@ module Honker
       until stop_fn.call
         acquired = lock_try_acquire(LEADER_LOCK, owner, LOCK_TTL_S)
         unless acquired
-          sleep_with_stop(5, stop_fn)
+          wait_for_update_or_timeout(5, stop_fn)
           next
         end
 
@@ -113,16 +125,6 @@ module Honker
             "stop must be callable (proc/lambda) or respond to :stop?"
     end
 
-    # Break sleeps into 1s increments so `stop` is honored promptly
-    # without busy-waiting.
-    def sleep_with_stop(total_s, stop_fn)
-      elapsed = 0
-      while elapsed < total_s && !stop_fn.call
-        sleep(1)
-        elapsed += 1
-      end
-    end
-
     def leader_loop(owner, stop_fn)
       last_heartbeat = monotonic_now
       until stop_fn.call
@@ -138,7 +140,18 @@ module Honker
 
           last_heartbeat = monotonic_now
         end
-        sleep(1)
+
+        wait_s = HEARTBEAT_S - (monotonic_now - last_heartbeat)
+        wait_s = 0 if wait_s.negative?
+
+        next_fire = soonest
+        if next_fire.positive?
+          until_next = next_fire - Time.now.to_i
+          until_next = 0 if until_next.negative?
+          wait_s = [wait_s, until_next].min
+        end
+
+        wait_for_update_or_timeout(wait_s, stop_fn)
       end
     end
 
@@ -146,6 +159,30 @@ module Honker
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    def data_version
+      @db.db.get_first_row("PRAGMA data_version")[0].to_i
+    end
+
+    def wait_for_update_or_timeout(total_s, stop_fn)
+      return if total_s <= 0
+
+      deadline = monotonic_now + total_s
+      last_version = data_version
+      last_local = @db.update_snapshot
+
+      until stop_fn.call
+        now = monotonic_now
+        break if now >= deadline
+
+        slice = [UPDATE_POLL_S, deadline - now].min
+        sleep(slice)
+
+        version = data_version
+        local = @db.update_snapshot
+        return if version != last_version || local != last_local
+      end
+    end
+
     def lock_try_acquire(name, owner, ttl_s)
       @db.db.get_first_row(
         "SELECT honker_lock_acquire(?, ?, ?)",

data/lib/honker/version.rb

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

data/lib/honker.rb

@@ -45,6 +45,7 @@ module Honker
 
     def initialize(path, extension_path:)
       @db = SQLite3::Database.new(path)
+      @local_update_seq = 0
       @db.enable_load_extension(true)
       @db.load_extension(extension_path)
       @db.enable_load_extension(false)
@@ -56,6 +57,14 @@ module Honker
       @db&.close
     end
 
+    def mark_updated
+      @local_update_seq += 1
+    end
+
+    def update_snapshot
+      @local_update_seq
+    end
+
     # Returns a Queue handle for a named queue.
     #
     #   visibility_timeout_s: 300   # claim expiry before reclaim
@@ -74,7 +83,7 @@ module Honker
       Stream.new(self, name)
     end
 
-    # Returns the cron-style Scheduler facade. Cheap — no allocation
+    # Returns the time-trigger Scheduler facade. Cheap — no allocation
     # beyond the wrapper object.
     def scheduler
       Scheduler.new(self)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: honker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Russell Romney
@@ -25,7 +25,7 @@ dependencies:
         version: '1.7'
 description: |-
   Ruby binding for Honker — a SQLite-native task runtime. Queues,
-  streams, pub/sub, cron scheduler, results, locks, rate limits, all
+  streams, pub/sub, time-trigger scheduler, results, locks, rate limits, all
   in one .db file. Thin wrapper around the Honker SQLite loadable
   extension; no Redis, no external broker.
 executables: []