honker 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf6de4cce9d9b068ecf07c59977f5ffea3295bcc55e3dc043033d8855bff648
-  data.tar.gz: 619580c9de45ccadb5ac20b41bea018c2ef5e11759f6d0a837d13c6239b76de4
+  metadata.gz: 04f540681d13eb8cbd385ba2f43d121d5273b73dfde940cf7f689047278fe08d
+  data.tar.gz: 1073ccdb529b22484fe275fff403c019963983dc250d145e68ece63abbfcb92b
 SHA512:
-  metadata.gz: 3ac9490e51f9dd4edca01a4a4af3a28ec3603113e2f02bbf54d80784d1d6c6946cc8c6c70d805acb3d1df3e84ec3d9d84ff5076901c07315888e35b1de7a25f1
-  data.tar.gz: db21f18ef6609c2cf330428d2518b21c903fd22dd64ec8156da3ce127ab03188181142d6d5872841e3d690e8ef2cf335a3f7494a2520b9887d3d51de8c0d8801
+  metadata.gz: 4b1ae556c89d8b2bdb5c77bc45936e8f465fc62a65f691da4e137df0e066283f209ab88b8064026c6649caf3626ec200f3cb76766705ef3324ad6edeefbec602
+  data.tar.gz: b6d8be9a6527d9cd8feb1ae6e57467d4e1c5e619c44823aa984fb52296402b917ab0215cef008bbc6d22eb88a7b5ab79385afcad688b90593f76182dd9bea33f

data/LICENSE

@@ -0,0 +1,6 @@
+Honker is licensed under either of:
+
+* Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
+* MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
+
+at your option.

data/LICENSE-APACHE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

data/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Russell Romney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,49 @@ 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}
-```
+You also need the Honker SQLite extension from the main repo.
 
-## Requirements
+## Watcher backends
 
-- Ruby 3.0+
-- `sqlite3` gem ≥ 1.7 (pulled in automatically)
+`Honker::Database.new(..., watcher_backend: "polling")` accepts the
+default polling backend aliases (`"polling"` / `"poll"`). Experimental
+`"kernel"` / `"shm"` requests route through `honker-core` via the loaded
+Honker extension and fail loudly if that extension was not built with
+the matching feature.
 
 ## 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.
-
-### `Queue#claim_batch(worker_id, n)` / `Queue#claim_one(worker_id)`
+Delayed jobs use `run_at:`:
 
-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,20 +10,24 @@ 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
   spec.homepage      = "https://honker.dev"
-  spec.license       = "Apache-2.0"
+  spec.licenses      = ["MIT", "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.files = Dir.glob("lib/**/*") + %w[honker.gemspec README.md LICENSE LICENSE-MIT LICENSE-APACHE]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "sqlite3", ">= 1.7"
+  # Honker loads the SQLite extension directly, so the Ruby sqlite3
+  # binding must expose Database#enable_load_extension/#load_extension.
+  # sqlite3 2.0.4 is the first line compatible with our Ruby >= 3.0 floor
+  # that reliably ships those APIs in the supported native builds.
+  spec.add_dependency "sqlite3", ">= 2.0.4", "< 3"
 end

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,20 @@ module Honker
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    def wait_for_update_or_timeout(total_s, stop_fn)
+      return if total_s <= 0
+
+      deadline = monotonic_now + total_s
+
+      until stop_fn.call
+        now = monotonic_now
+        break if now >= deadline
+
+        slice = [0.1, deadline - now].min
+        return if @db.wait_for_update(slice)
+      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.2"
 end

data/lib/honker.rb

@@ -18,6 +18,7 @@
 # is one SQL call via the `sqlite3` gem. No extra process, no Redis.
 
 require "json"
+require "fiddle"
 require "sqlite3"
 
 require_relative "honker/version"
@@ -27,10 +28,52 @@ require_relative "honker/scheduler"
 require_relative "honker/lock"
 
 module Honker
+  class CoreWatcher
+    def initialize(db_path, extension_path, backend)
+      @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],
+        Fiddle::TYPE_VOIDP,
+      )
+      @wait = Fiddle::Function.new(
+        @lib["honker_watcher_wait"],
+        [Fiddle::TYPE_VOIDP, Fiddle::TYPE_LONG_LONG],
+        Fiddle::TYPE_INT,
+      )
+      @close = Fiddle::Function.new(
+        @lib["honker_watcher_close"],
+        [Fiddle::TYPE_VOIDP],
+        Fiddle::TYPE_VOID,
+      )
+      err = "\0" * 1024
+      @handle = @open.call(db_path.to_s, backend.to_s, err, err.bytesize)
+      return unless @handle.to_i.zero?
+
+      raise ArgumentError, err.delete_suffix("\0").split("\0", 2).first
+    end
+
+    def wait(timeout_s)
+      code = @wait.call(@handle, (timeout_s * 1000).ceil)
+      return true if code == 1
+      return false if code == 0
+
+      raise Error, "honker update watcher closed or died"
+    end
+
+    def close
+      return if @handle.nil? || @handle.to_i.zero?
+
+      @close.call(@handle)
+      @handle = nil
+    end
+  end
+
   DEFAULT_PRAGMAS = <<~SQL
     PRAGMA journal_mode = WAL;
     PRAGMA synchronous = NORMAL;
     PRAGMA busy_timeout = 5000;
+    PRAGMA mmap_size = 0;
     PRAGMA foreign_keys = ON;
     PRAGMA cache_size = -32000;
     PRAGMA temp_store = MEMORY;
@@ -43,19 +86,40 @@ module Honker
   class Database
     attr_reader :db
 
-    def initialize(path, extension_path:)
+    def initialize(path, extension_path:, watcher_backend: nil)
+      unless watcher_backend.nil? || watcher_backend.is_a?(String)
+        raise ArgumentError, "unknown watcher backend"
+      end
+
       @db = SQLite3::Database.new(path)
+      @local_update_seq = 0
+      @db.busy_timeout = 5000
+      @db.execute("PRAGMA mmap_size = 0")
       @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()")
+      @watcher = CoreWatcher.new(path, extension_path, watcher_backend)
     end
 
     def close
+      @watcher&.close
       @db&.close
     end
 
+    def mark_updated
+      @local_update_seq += 1
+    end
+
+    def update_snapshot
+      @local_update_seq
+    end
+
+    def wait_for_update(timeout_s)
+      @watcher.wait(timeout_s)
+    end
+
     # Returns a Queue handle for a named queue.
     #
     #   visibility_timeout_s: 300   # claim expiry before reclaim
@@ -69,12 +133,24 @@ module Honker
       )
     end
 
+    # Transactional side-effect delivery built on a reserved queue.
+    def outbox(name, delivery, visibility_timeout_s: 60, max_attempts: 5, base_backoff_s: 5)
+      Outbox.new(
+        self,
+        name,
+        delivery,
+        visibility_timeout_s: visibility_timeout_s,
+        max_attempts: max_attempts,
+        base_backoff_s: base_backoff_s,
+      )
+    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
+    # Returns the time-trigger Scheduler facade. Cheap — no allocation
     # beyond the wrapper object.
     def scheduler
       Scheduler.new(self)
@@ -274,6 +350,65 @@ module Honker
     end
   end
 
+  class Outbox
+    attr_reader :name, :queue, :max_attempts, :base_backoff_s
+
+    def initialize(db, name, delivery, visibility_timeout_s:, max_attempts:, base_backoff_s:)
+      raise ArgumentError, "delivery must respond to #call" unless delivery.respond_to?(:call)
+
+      @name = name
+      @delivery = delivery
+      @max_attempts = max_attempts
+      @base_backoff_s = base_backoff_s
+      @queue = db.queue(
+        "_outbox:#{name}",
+        visibility_timeout_s: visibility_timeout_s,
+        max_attempts: max_attempts,
+      )
+    end
+
+    def enqueue(payload, tx: nil, delay: nil, run_at: nil, priority: 0, expires: nil)
+      if tx
+        @queue.enqueue_tx(tx, payload, delay: delay, run_at: run_at, priority: priority, expires: expires)
+      else
+        @queue.enqueue(payload, delay: delay, run_at: run_at, priority: priority, expires: expires)
+      end
+    end
+
+    def run_once(worker_id)
+      job = @queue.claim_one(worker_id)
+      return false unless job
+
+      begin
+        if @delivery.arity == 1
+          @delivery.call(job.payload)
+        else
+          @delivery.call(job.payload, job)
+        end
+        raise "outbox ack failed for job #{job.id}" unless job.ack
+      rescue StandardError => e
+        delay_s = retry_delay(job.attempts)
+        raise "outbox retry failed for job #{job.id}" unless job.retry(delay_s: delay_s, error: "#{e}\n#{e.backtrace&.join("\n")}")
+      end
+      true
+    end
+
+    def run_worker(worker_id, stop: nil, idle_sleep_s: 0.1)
+      until stop&.call
+        processed = run_once(worker_id)
+        sleep(idle_sleep_s) unless processed
+      end
+    end
+
+    private
+
+    def retry_delay(attempts)
+      return 0 if @base_backoff_s <= 0
+
+      (@base_backoff_s * (2**[attempts - 1, 0].max)).ceil
+    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.

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: honker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Russell Romney
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
@@ -15,23 +16,33 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: 2.0.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: 2.0.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 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.
+email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- LICENSE-APACHE
+- LICENSE-MIT
 - README.md
 - honker.gemspec
 - lib/honker.rb
@@ -42,11 +53,13 @@ files:
 - lib/honker/version.rb
 homepage: https://honker.dev
 licenses:
+- MIT
 - Apache-2.0
 metadata:
   homepage_uri: https://honker.dev
   source_code_uri: https://github.com/russellromney/honker
   documentation_uri: https://honker.dev/
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -61,7 +74,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Durable queues, streams, pub/sub, and scheduler on SQLite.
 test_files: []