honker 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41df996d169333da2b22d08dbb613537c16c1d92519e86558986b11737406bda
-  data.tar.gz: c052dd0d545ea520914e650b488138b1512527f1278c3e7c4bf72932c40df055
+  metadata.gz: 04f540681d13eb8cbd385ba2f43d121d5273b73dfde940cf7f689047278fe08d
+  data.tar.gz: 1073ccdb529b22484fe275fff403c019963983dc250d145e68ece63abbfcb92b
 SHA512:
-  metadata.gz: 414c0d65e26bb76e4a6aad15674b32a448fefc75ca13ad060cc570fa86e5b0180efa5875859e08def6afd0b9c92f9eb42f26d7420478abc7a50d9ec9ab133550
-  data.tar.gz: 78c16c3beea3611f590602f338ec7aa6e5d27edb9a2ffa81b8267c64a835fd129f07562bbbf6c67d6d4fb386421b5a2d965c3a7454c26f21afe76ee7a29ade36
+  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

@@ -15,6 +15,14 @@ gem "honker"
 
 You also need the Honker SQLite extension from the main repo.
 
+## Watcher backends
+
+`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

data/honker.gemspec

@@ -15,15 +15,19 @@ Gem::Specification.new do |spec|
     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

@@ -159,27 +159,17 @@ 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
+        slice = [0.1, deadline - now].min
+        return if @db.wait_for_update(slice)
       end
     end
 

data/lib/honker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Honker
-  VERSION = "0.1.1"
+  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,17 +86,25 @@ 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
 
@@ -65,6 +116,10 @@ module Honker
       @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
@@ -78,6 +133,18 @@ 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)
@@ -283,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.1
+  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, 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: []