honker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fbf6de4cce9d9b068ecf07c59977f5ffea3295bcc55e3dc043033d8855bff648
+  data.tar.gz: 619580c9de45ccadb5ac20b41bea018c2ef5e11759f6d0a837d13c6239b76de4
+SHA512:
+  metadata.gz: 3ac9490e51f9dd4edca01a4a4af3a28ec3603113e2f02bbf54d80784d1d6c6946cc8c6c70d805acb3d1df3e84ec3d9d84ff5076901c07315888e35b1de7a25f1
+  data.tar.gz: db21f18ef6609c2cf330428d2518b21c903fd22dd64ec8156da3ce127ab03188181142d6d5872841e3d690e8ef2cf335a3f7494a2520b9887d3d51de8c0d8801

data/README.md

@@ -0,0 +1,88 @@
+# honker (Ruby)
+
+Ruby binding for [Honker](https://honker.dev) — durable queues, streams, pub/sub, and scheduler on SQLite.
+
+## Install
+
+```ruby
+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)
+
+## Quick start
+
+```ruby
+require "honker"
+
+db = Honker::Database.new("app.db", extension_path: "./libhonker_extension.dylib")
+q  = db.queue("emails")
+
+# Enqueue (atomic-with-your-write via business transactions; see below)
+q.enqueue({ to: "alice@example.com" })
+
+# Claim + process + ack
+job = q.claim_one("worker-1")
+if job
+  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.
+
+### `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
+
+- `listen` / WAL-based async iterator (watcher API — in progress)
+- Streams (durable pub/sub with per-consumer offsets)
+- Scheduler (cron-style periodic tasks)
+
+All available via raw SQL on the same database (`db.db.execute("SELECT honker_stream_publish(...)")`). Idiomatic Ruby wrappers coming in a future release.
+
+## Testing
+
+```bash
+# Build the extension
+cd /path/to/honker && cargo build --release -p honker-extension
+
+# Run the tests
+cd packages/honker-ruby
+bundle install
+bundle exec rake test     # or: ruby -Ilib -Ispec spec/honker_spec.rb
+```

data/honker.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/honker/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "honker"
+  spec.version       = Honker::VERSION
+  spec.authors       = ["Russell Romney"]
+
+  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
+    in one .db file. Thin wrapper around the Honker SQLite loadable
+    extension; no Redis, no external broker.
+  DESC
+  spec.homepage      = "https://honker.dev"
+  spec.license       = "Apache-2.0"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/russellromney/honker"
+  spec.metadata["documentation_uri"] = "https://honker.dev/"
+
+  spec.files = Dir.glob("lib/**/*") + %w[honker.gemspec README.md]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "sqlite3", ">= 1.7"
+end

data/lib/honker/lock.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Honker
+  # Advisory lock. Returned by `Database#try_lock`; `nil` means another
+  # owner holds it.
+  #
+  # Prefer explicit `release` — finalizers are best-effort. Holding the
+  # `Lock` instance does NOT guarantee you still own the lock; the
+  # extension's TTL can expire and a new owner take it. Use
+  # `heartbeat(ttl_s:)` periodically and check its return value.
+  class Lock
+    attr_reader :name, :owner
+
+    def initialize(db, name, owner)
+      @db = db
+      @name = name
+      @owner = owner
+      @released = false
+      # Best-effort cleanup if the caller forgets to release. We capture
+      # closed-over primitives (not `self`) so the finalizer can run
+      # without keeping the Lock itself alive.
+      ObjectSpace.define_finalizer(self, self.class._finalizer(db, name, owner))
+    end
+
+    # Class-level factory so the finalizer doesn't close over `self`.
+    def self._finalizer(db, name, owner)
+      proc do
+        begin
+          db.db.get_first_row(
+            "SELECT honker_lock_release(?, ?)",
+            [name, owner],
+          )
+        rescue StandardError
+          # Finalizers run after the interpreter teardown can begin;
+          # swallowing is the only safe option here.
+        end
+      end
+    end
+
+    # Release the lock. Idempotent — calling release twice is a no-op
+    # on the second call.
+    def release
+      return false if @released
+
+      @released = true
+      @db.db.get_first_row(
+        "SELECT honker_lock_release(?, ?)",
+        [@name, @owner],
+      )[0] == 1
+    end
+
+    # True if the caller has already released this handle.
+    def released?
+      @released
+    end
+
+    # Extend the TTL. Returns true if we still hold the lock; false if
+    # it was stolen (the TTL elapsed and another owner acquired it).
+    # The underlying SQL is the same as `try_lock`, but keyed on our
+    # existing `(name, owner)` pair so it refreshes rather than blocks.
+    def heartbeat(ttl_s:)
+      @db.db.get_first_row(
+        "SELECT honker_lock_acquire(?, ?, ?)",
+        [@name, @owner, ttl_s],
+      )[0] == 1
+    end
+  end
+end

data/lib/honker/scheduler.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Honker
+  # Fired on each scheduler tick that enqueued a job.
+  ScheduledFire = Struct.new(:name, :queue, :fire_at, :job_id) do
+    def self.from_row(row)
+      new(row["name"], row["queue"], row["fire_at"], row["job_id"])
+    end
+  end
+
+  # Cron-style 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.
+  class Scheduler
+    # Lock name used for leader election in `run`. Constant so all
+    # processes contending for leader share a single lock row.
+    LEADER_LOCK = "honker-scheduler"
+
+    # TTL on the leader lock. Refreshed from `run` every HEARTBEAT_S;
+    # a leader whose refresh fails drops out of the loop so a standby
+    # can pick up without waiting the full TTL.
+    LOCK_TTL_S = 60
+
+    # Refresh cadence. Balance: too small and every tick is a lock
+    # write; too large and a standby waits longer than necessary after
+    # a crash. Matches the Rust binding.
+    HEARTBEAT_S = 20
+
+    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)
+      @db.db.get_first_row(
+        "SELECT honker_scheduler_register(?, ?, ?, ?, ?, ?)",
+        [name, queue, cron, JSON.dump(payload), priority, expires_s],
+      )
+      nil
+    end
+
+    # Remove a registered task by name. Returns the count deleted
+    # (0 or 1).
+    def remove(name)
+      @db.db.get_first_row(
+        "SELECT honker_scheduler_unregister(?)",
+        [name],
+      )[0]
+    end
+
+    # Fire all due boundaries at `now`. Returns an array of
+    # ScheduledFire — one per enqueued job.
+    def tick(now = Time.now.to_i)
+      rows_json = @db.db.get_first_row(
+        "SELECT honker_scheduler_tick(?)",
+        [now],
+      )[0]
+      JSON.parse(rows_json).map { |r| ScheduledFire.from_row(r) }
+    end
+
+    # Soonest `next_fire_at` across all tasks, or 0 if no tasks.
+    def soonest
+      @db.db.get_first_row("SELECT honker_scheduler_soonest()")[0]
+    end
+
+    # Run the scheduler loop with leader election. Blocks until `stop`
+    # signals. `stop` is any object that responds to `call` (returning
+    # truthy to stop) — a common choice is a lambda backed by a Mutex-
+    # guarded flag, or an `AtomicBoolean`-like wrapper.
+    #
+    # Only the process holding the `"honker-scheduler"` advisory lock
+    # fires. Standbys sleep 5s and retry. The leader heartbeats every
+    # 20s; if the refresh fails (returns 0), we break out of the leader
+    # loop immediately so we don't double-fire alongside a new leader
+    # that acquired the lock after our TTL elapsed.
+    #
+    # `owner` distinguishes processes — typically a hostname + pid.
+    # On tick error, the lock is released before re-raising so a
+    # standby can pick up without waiting the full TTL.
+    def run(owner:, stop:)
+      stop_fn = normalize_stop(stop)
+      until stop_fn.call
+        acquired = lock_try_acquire(LEADER_LOCK, owner, LOCK_TTL_S)
+        unless acquired
+          sleep_with_stop(5, stop_fn)
+          next
+        end
+
+        begin
+          leader_loop(owner, stop_fn)
+        ensure
+          lock_release(LEADER_LOCK, owner)
+        end
+      end
+      nil
+    end
+
+    private
+
+    # Convert a user-supplied stop arg into a zero-arg callable. Accept
+    # a proc/lambda, anything with `#call`, a `Queue` (drained = stop),
+    # or a mutex-guarded flag object with `#stop?`.
+    def normalize_stop(stop)
+      return stop if stop.respond_to?(:call) && stop.arity.zero?
+      return -> { stop.call } if stop.respond_to?(:call)
+      return -> { stop.stop? } if stop.respond_to?(:stop?)
+
+      raise ArgumentError,
+            "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
+        # tick errors escape up to `run`, which releases the lock in
+        # its `ensure` before re-raising.
+        tick
+        if monotonic_now - last_heartbeat >= HEARTBEAT_S
+          still_ours = lock_try_acquire(LEADER_LOCK, owner, LOCK_TTL_S)
+          # IMPORTANT: if refresh failed, a new leader has the lock.
+          # Break out of the leader loop so we don't double-fire. This
+          # is the bug the Rust binding fixed; don't reintroduce it.
+          return unless still_ours
+
+          last_heartbeat = monotonic_now
+        end
+        sleep(1)
+      end
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def lock_try_acquire(name, owner, ttl_s)
+      @db.db.get_first_row(
+        "SELECT honker_lock_acquire(?, ?, ?)",
+        [name, owner, ttl_s],
+      )[0] == 1
+    end
+
+    def lock_release(name, owner)
+      @db.db.get_first_row(
+        "SELECT honker_lock_release(?, ?)",
+        [name, owner],
+      )[0] == 1
+    end
+  end
+end

data/lib/honker/stream.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Honker
+  # An append-only ordered log. Publish writes an offset-stamped event;
+  # consumers resume from a saved offset. Mirrors the typed API in the
+  # Rust binding.
+  #
+  #   s = db.stream("orders")
+  #   off = s.publish({ id: 1 })
+  #   events = s.read_since(0, 100)
+  #   s.save_offset("billing", events.last.offset)
+  class Stream
+    attr_reader :topic
+
+    def initialize(db, topic)
+      @db = db
+      @topic = topic
+    end
+
+    # Publish an event. Returns the assigned offset.
+    def publish(payload)
+      publish_with_key_opt(nil, payload)
+    end
+
+    # Publish with a partition key — used by downstream consumers that
+    # want per-key ordering.
+    def publish_with_key(key, payload)
+      publish_with_key_opt(key, payload)
+    end
+
+    # Publish inside an open transaction. The event is visible to
+    # readers only after the transaction commits.
+    def publish_tx(tx, payload)
+      row = tx.query_row(
+        "SELECT honker_stream_publish(?, NULL, ?)",
+        [@topic, JSON.dump(payload)],
+      )
+      row[0]
+    end
+
+    # Read events with offset > `offset`, up to `limit`. Returns an
+    # array of StreamEvent.
+    def read_since(offset, limit)
+      rows_json = @db.db.get_first_row(
+        "SELECT honker_stream_read_since(?, ?, ?)",
+        [@topic, offset, limit],
+      )[0]
+      JSON.parse(rows_json).map { |r| StreamEvent.from_row(r) }
+    end
+
+    # Read events newer than this consumer's saved offset. Does NOT
+    # advance the offset — call `save_offset` after processing.
+    def read_from_consumer(consumer, limit)
+      read_since(get_offset(consumer), limit)
+    end
+
+    # Save a consumer's offset. Monotonic: saving a lower offset is
+    # ignored by the extension and returns false.
+    def save_offset(consumer, offset)
+      @db.db.get_first_row(
+        "SELECT honker_stream_save_offset(?, ?, ?)",
+        [consumer, @topic, offset],
+      )[0] == 1
+    end
+
+    # Save offset inside an open transaction. Gives you exactly-once
+    # semantics relative to whatever else ran on the same tx.
+    def save_offset_tx(tx, consumer, offset)
+      row = tx.query_row(
+        "SELECT honker_stream_save_offset(?, ?, ?)",
+        [consumer, @topic, offset],
+      )
+      row[0] == 1
+    end
+
+    # Current saved offset for `consumer`, or 0 if never saved.
+    def get_offset(consumer)
+      @db.db.get_first_row(
+        "SELECT honker_stream_get_offset(?, ?)",
+        [consumer, @topic],
+      )[0]
+    end
+
+    private
+
+    def publish_with_key_opt(key, payload)
+      @db.db.get_first_row(
+        "SELECT honker_stream_publish(?, ?, ?)",
+        [@topic, key, JSON.dump(payload)],
+      )[0]
+    end
+  end
+
+  # One event in a stream. `payload` is already JSON-decoded.
+  StreamEvent = Struct.new(:offset, :topic, :key, :payload, :created_at) do
+    def self.from_row(row)
+      new(
+        row["offset"],
+        row["topic"],
+        row["key"],
+        row["payload"].nil? ? nil : JSON.parse(row["payload"]),
+        row["created_at"],
+      )
+    end
+  end
+end

data/lib/honker/transaction.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Honker
+  # Wraps a SQLite transaction with helpers that thread SQL through a
+  # stable connection handle. Matches the shape of the Rust binding's
+  # `Transaction` — `execute` and `query_row` route to the underlying
+  # connection, which `*_tx` methods (`Queue#enqueue_tx`,
+  # `Stream#publish_tx`, `Stream#save_offset_tx`, `Database#notify_tx`)
+  # use to stay inside the open transaction.
+  #
+  # Obtain one via `Database#transaction do |tx| ... end`. The block
+  # auto-commits on normal return and auto-rolls-back on exception; the
+  # wrapping `sqlite3` gem handles the BEGIN/COMMIT/ROLLBACK for us.
+  # Callers may also invoke `tx.rollback!` mid-block to abort without
+  # raising.
+  class Transaction
+    # The raw `SQLite3::Database` underneath. Exposed as `conn` to
+    # mirror the Rust shape for advanced users who need `prepare` or
+    # other APIs not wrapped here.
+    attr_reader :conn
+
+    def initialize(conn)
+      @conn = conn
+      @rolled_back = false
+    end
+
+    # Execute a SQL statement inside the transaction.
+    def execute(sql, params = [])
+      @conn.execute(sql, params)
+    end
+
+    # Run a query and return the first row (or nil).
+    def query_row(sql, params = [])
+      @conn.get_first_row(sql, params)
+    end
+
+    # Abort the transaction early. Raises `Transaction::Rollback`
+    # internally so the outer sqlite3-gem block sees an exception and
+    # rolls back; we then swallow it at the `Database#transaction`
+    # boundary.
+    def rollback!
+      @rolled_back = true
+      raise Rollback
+    end
+
+    def rolled_back?
+      @rolled_back
+    end
+
+    # Sentinel to unwind the sqlite3 gem's transaction block without
+    # surfacing as a user-visible exception.
+    class Rollback < StandardError; end
+  end
+end

data/lib/honker/version.rb

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

data/lib/honker.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+#
+# Ruby binding for Honker — a SQLite-native task runtime.
+#
+# Usage:
+#
+#   require "honker"
+#
+#   db = Honker::Database.new("app.db", extension_path: "./libhonker.dylib")
+#   q  = db.queue("emails")
+#   q.enqueue({to: "alice@example.com"})
+#
+#   job = q.claim_one("worker-1")
+#   send_email(job.payload) if job
+#   job&.ack
+#
+# Thin wrapper around the Honker SQLite loadable extension — each method
+# is one SQL call via the `sqlite3` gem. No extra process, no Redis.
+
+require "json"
+require "sqlite3"
+
+require_relative "honker/version"
+require_relative "honker/transaction"
+require_relative "honker/stream"
+require_relative "honker/scheduler"
+require_relative "honker/lock"
+
+module Honker
+  DEFAULT_PRAGMAS = <<~SQL
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA busy_timeout = 5000;
+    PRAGMA foreign_keys = ON;
+    PRAGMA cache_size = -32000;
+    PRAGMA temp_store = MEMORY;
+    PRAGMA wal_autocheckpoint = 10000;
+  SQL
+
+  # Database is a Honker handle over a SQLite file with the Honker
+  # extension loaded. The constructor bootstraps the schema; safe to
+  # open the same path from multiple processes.
+  class Database
+    attr_reader :db
+
+    def initialize(path, extension_path:)
+      @db = SQLite3::Database.new(path)
+      @db.enable_load_extension(true)
+      @db.load_extension(extension_path)
+      @db.enable_load_extension(false)
+      @db.execute_batch(DEFAULT_PRAGMAS)
+      @db.execute("SELECT honker_bootstrap()")
+    end
+
+    def close
+      @db&.close
+    end
+
+    # Returns a Queue handle for a named queue.
+    #
+    #   visibility_timeout_s: 300   # claim expiry before reclaim
+    #   max_attempts:         3     # retries before moving to dead
+    def queue(name, visibility_timeout_s: 300, max_attempts: 3)
+      Queue.new(
+        self,
+        name,
+        visibility_timeout_s: visibility_timeout_s,
+        max_attempts: max_attempts,
+      )
+    end
+
+    # Returns a Stream handle for an append-only ordered log.
+    def stream(name)
+      Stream.new(self, name)
+    end
+
+    # Returns the cron-style Scheduler facade. Cheap — no allocation
+    # beyond the wrapper object.
+    def scheduler
+      Scheduler.new(self)
+    end
+
+    # Fire a pg_notify-style pub/sub signal. Returns the notification id.
+    def notify(channel, payload)
+      row = @db.get_first_row("SELECT notify(?, ?)", [channel, JSON.dump(payload)])
+      row[0]
+    end
+
+    # Fire a notification inside an open transaction. The signal lands
+    # only when the transaction commits.
+    def notify_tx(tx, channel, payload)
+      row = tx.query_row(
+        "SELECT notify(?, ?)",
+        [channel, JSON.dump(payload)],
+      )
+      row[0]
+    end
+
+    # Run a block inside a SQLite transaction. The block receives a
+    # Honker::Transaction; returning normally commits, raising rolls
+    # back, and `tx.rollback!` rolls back without surfacing an error.
+    #
+    #   db.transaction do |tx|
+    #     tx.execute("INSERT INTO orders ...")
+    #     q.enqueue_tx(tx, {order_id: 1})
+    #   end
+    def transaction
+      tx = Transaction.new(@db)
+      begin
+        @db.transaction do
+          yield tx
+        end
+      rescue Transaction::Rollback
+        # Caller used tx.rollback! to abort. The block exited with an
+        # exception so the sqlite3 gem already rolled back — just
+        # swallow the sentinel.
+        nil
+      end
+    end
+
+    # Try to acquire an advisory lock. Returns a `Lock` handle on
+    # success, `nil` if another owner holds it.
+    def try_lock(name, owner:, ttl_s:)
+      acquired = @db.get_first_row(
+        "SELECT honker_lock_acquire(?, ?, ?)",
+        [name, owner, ttl_s],
+      )[0]
+      return nil unless acquired == 1
+
+      Lock.new(self, name, owner)
+    end
+
+    # Fixed-window rate limiter. Returns true if this call fits within
+    # `limit` requests per `per` seconds.
+    def try_rate_limit(name, limit:, per:)
+      @db.get_first_row(
+        "SELECT honker_rate_limit_try(?, ?, ?)",
+        [name, limit, per],
+      )[0] == 1
+    end
+
+    # Sweep old rate-limit window rows. Returns count deleted.
+    def sweep_rate_limits(older_than_s:)
+      @db.get_first_row(
+        "SELECT honker_rate_limit_sweep(?)",
+        [older_than_s],
+      )[0]
+    end
+
+    # Persist a job result for later retrieval via `get_result`.
+    # `value` is stored verbatim — JSON-encode it yourself if you want
+    # to round-trip structured data.
+    def save_result(job_id, value, ttl_s:)
+      @db.get_first_row(
+        "SELECT honker_result_save(?, ?, ?)",
+        [job_id, value, ttl_s],
+      )
+      nil
+    end
+
+    # Fetch a stored result, or nil if absent or expired.
+    def get_result(job_id)
+      @db.get_first_row(
+        "SELECT honker_result_get(?)",
+        [job_id],
+      )[0]
+    end
+
+    # Drop expired result rows. Returns count swept.
+    def sweep_results
+      @db.get_first_row("SELECT honker_result_sweep()")[0]
+    end
+
+    # Delete notifications older than `older_than_s` seconds. Returns
+    # the number of rows deleted.
+    def prune_notifications(older_than_s:)
+      @db.execute(
+        "DELETE FROM _honker_notifications WHERE created_at < unixepoch() - ?",
+        [older_than_s],
+      )
+      @db.changes
+    end
+  end
+
+  class Queue
+    attr_reader :name, :max_attempts
+
+    def initialize(db, name, visibility_timeout_s:, max_attempts:)
+      @db = db
+      @name = name
+      @visibility_timeout_s = visibility_timeout_s
+      @max_attempts = max_attempts
+    end
+
+    # Enqueue a job. Returns the inserted row id.
+    #
+    #   q.enqueue({to: "alice"}, delay: 60, priority: 10, expires: 3600)
+    def enqueue(payload, delay: nil, run_at: nil, priority: 0, expires: nil)
+      row = @db.db.get_first_row(
+        "SELECT honker_enqueue(?, ?, ?, ?, ?, ?, ?)",
+        [@name, JSON.dump(payload), run_at, delay, priority, @max_attempts, expires],
+      )
+      row[0]
+    end
+
+    # Enqueue inside an open transaction. Atomic with whatever else ran
+    # on the same tx.
+    def enqueue_tx(tx, payload, delay: nil, run_at: nil, priority: 0, expires: nil)
+      row = tx.query_row(
+        "SELECT honker_enqueue(?, ?, ?, ?, ?, ?, ?)",
+        [@name, JSON.dump(payload), run_at, delay, priority, @max_attempts, expires],
+      )
+      row[0]
+    end
+
+    # Claim up to n jobs atomically. Returns an array of Job.
+    def claim_batch(worker_id, n)
+      rows_json = @db.db.get_first_row(
+        "SELECT honker_claim_batch(?, ?, ?, ?)",
+        [@name, worker_id, n, @visibility_timeout_s],
+      )[0]
+      JSON.parse(rows_json).map { |r| Job.new(self, r) }
+    end
+
+    # Claim a single job or nil if the queue is empty.
+    def claim_one(worker_id)
+      claim_batch(worker_id, 1).first
+    end
+
+    # Ack multiple jobs in one transaction. Returns the number acked.
+    def ack_batch(ids, worker_id)
+      @db.db.get_first_row(
+        "SELECT honker_ack_batch(?, ?)",
+        [JSON.dump(ids), worker_id],
+      )[0]
+    end
+
+    # Sweep this queue's expired claims back to pending. Returns the
+    # number of rows reclaimed.
+    def sweep_expired
+      @db.db.get_first_row(
+        "SELECT honker_sweep_expired(?)",
+        [@name],
+      )[0]
+    end
+
+    # Internal: invoked by Job#ack.
+    def _ack(job_id, worker_id)
+      @db.db.get_first_row("SELECT honker_ack(?, ?)", [job_id, worker_id])[0] == 1
+    end
+
+    # Internal: invoked by Job#retry.
+    def _retry(job_id, worker_id, delay_s, err_msg)
+      @db.db.get_first_row(
+        "SELECT honker_retry(?, ?, ?, ?)",
+        [job_id, worker_id, delay_s, err_msg],
+      )[0] == 1
+    end
+
+    # Internal: invoked by Job#fail.
+    def _fail(job_id, worker_id, err_msg)
+      @db.db.get_first_row(
+        "SELECT honker_fail(?, ?, ?)",
+        [job_id, worker_id, err_msg],
+      )[0] == 1
+    end
+
+    # Internal: invoked by Job#heartbeat.
+    def _heartbeat(job_id, worker_id, extend_s)
+      @db.db.get_first_row(
+        "SELECT honker_heartbeat(?, ?, ?)",
+        [job_id, worker_id, extend_s],
+      )[0] == 1
+    end
+  end
+
+  # A claimed unit of work. `payload` is the decoded JSON value (Hash,
+  # Array, etc.). `id`, `worker_id`, and `attempts` are metadata from
+  # the claim result.
+  class Job
+    attr_reader :id, :queue_name, :payload, :worker_id, :attempts
+
+    def initialize(queue, row)
+      @queue = queue
+      @id = row["id"]
+      @queue_name = row["queue"]
+      @payload = JSON.parse(row["payload"]) unless row["payload"].nil?
+      @worker_id = row["worker_id"]
+      @attempts = row["attempts"]
+    end
+
+    # DELETEs the row if the claim is still valid. Returns true/false.
+    def ack
+      @queue._ack(@id, @worker_id)
+    end
+
+    # Returns the job to pending with a delay, or moves it to dead
+    # after max_attempts. Returns true iff the claim was valid.
+    def retry(delay_s: 60, error: "")
+      @queue._retry(@id, @worker_id, delay_s, error)
+    end
+
+    # Unconditionally moves the claim to dead.
+    def fail(error: "")
+      @queue._fail(@id, @worker_id, error)
+    end
+
+    # Extend the claim's visibility timeout.
+    def heartbeat(extend_s:)
+      @queue._heartbeat(@id, @worker_id, extend_s)
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: honker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Russell Romney
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: |-
+  Ruby binding for Honker — a SQLite-native task runtime. Queues,
+  streams, pub/sub, cron scheduler, results, locks, rate limits, all
+  in one .db file. Thin wrapper around the Honker SQLite loadable
+  extension; no Redis, no external broker.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- honker.gemspec
+- lib/honker.rb
+- lib/honker/lock.rb
+- lib/honker/scheduler.rb
+- lib/honker/stream.rb
+- lib/honker/transaction.rb
+- lib/honker/version.rb
+homepage: https://honker.dev
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://honker.dev
+  source_code_uri: https://github.com/russellromney/honker
+  documentation_uri: https://honker.dev/
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Durable queues, streams, pub/sub, and scheduler on SQLite.
+test_files: []