honker 0.1.2 → 0.3.0

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

@@ -0,0 +1,330 @@
+//! honker SQLite loadable extension.
+//!
+//! Thin wrapper around `honker-core`. Registers:
+//!
+//!   * `notify()` SQL scalar function + `_honker_notifications`
+//!     table — via `honker_core::attach_notify`.
+//!   * Every `honker_*` queue / lock / rate-limit / scheduler / result
+//!     function — via `honker_core::attach_honker_functions`.
+//!
+//!     .load ./libhonker_ext
+//!     SELECT honker_bootstrap();
+//!     INSERT INTO _honker_live (queue, payload)
+//!     VALUES ('emails', '{"to": "alice"}');
+//!     SELECT honker_claim_batch('emails', 'worker-1', 32, 300);
+//!     SELECT honker_ack_batch('[1,2,3]', 'worker-1');
+//!     SELECT notify('orders', '{"id": 42}');
+//!
+//! Actual SQL implementations live in `honker_core::honker_ops`
+//! so the Python (PyO3) and Node (napi-rs) bindings can register the
+//! same functions on their own connections without loading this
+//! `.dylib`. One source of truth for the SQL.
+
+use rusqlite::ffi;
+use rusqlite::functions::FunctionFlags;
+use rusqlite::{Connection, Error, Result};
+use std::collections::HashMap;
+use std::ffi::CStr;
+use std::os::raw::{c_char, c_int};
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::Mutex as StdMutex;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::mpsc::{Receiver, RecvTimeoutError};
+use std::time::Duration;
+use std::{ptr, sync::LazyLock};
+
+fn panic_error(payload: Box<dyn std::any::Any + Send>) -> Error {
+    let msg = if let Some(s) = payload.downcast_ref::<&str>() {
+        *s
+    } else if let Some(s) = payload.downcast_ref::<String>() {
+        s.as_str()
+    } else {
+        "non-string panic payload"
+    };
+    Error::UserFunctionError(Box::new(std::io::Error::other(format!(
+        "honker extension initialization panicked: {msg}"
+    ))))
+}
+
+fn extension_init(conn: Connection) -> Result<bool> {
+    match catch_unwind(AssertUnwindSafe(|| {
+        honker_core::attach_notify(&conn).map_err(|e| {
+            Error::UserFunctionError(Box::new(std::io::Error::other(e.to_string())))
+        })?;
+        honker_core::attach_honker_functions(&conn)?;
+        attach_watcher_sql_functions(&conn)?;
+        Ok(true)
+    })) {
+        Ok(result) => result,
+        Err(payload) => Err(panic_error(payload)),
+    }
+}
+
+static SQL_WATCHERS: LazyLock<StdMutex<HashMap<u64, HonkerWatcherHandle>>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+static NEXT_SQL_WATCHER_ID: AtomicU64 = AtomicU64::new(1);
+
+fn open_watcher_handle(
+    db_path: &str,
+    backend: Option<&str>,
+) -> 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 shared = Arc::new(honker_core::SharedUpdateWatcher::new_with_config(
+        PathBuf::from(db_path),
+        honker_core::WatcherConfig { backend },
+    ));
+    let (sub_id, rx) = shared.subscribe();
+    Ok(HonkerWatcherHandle { shared, sub_id, rx })
+}
+
+fn attach_watcher_sql_functions(conn: &Connection) -> Result<()> {
+    conn.create_scalar_function(
+        "honker_update_watcher_open",
+        2,
+        FunctionFlags::SQLITE_UTF8,
+        |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| {
+                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,
+        FunctionFlags::SQLITE_UTF8,
+        |ctx| {
+            let id: i64 = ctx.get(0)?;
+            let timeout_ms: i64 = ctx.get(1)?;
+            let Some(handle) = SQL_WATCHERS.lock().unwrap().remove(&(id as u64)) else {
+                return Ok(-1);
+            };
+            let timeout_ms = timeout_ms.max(0) as u64;
+            let code = match handle.rx.recv_timeout(Duration::from_millis(timeout_ms)) {
+                Ok(()) => 1,
+                Err(RecvTimeoutError::Timeout) => 0,
+                Err(RecvTimeoutError::Disconnected) => -1,
+            };
+            if code != -1 {
+                SQL_WATCHERS.lock().unwrap().insert(id as u64, handle);
+            } else {
+                handle.shared.unsubscribe(handle.sub_id);
+                let _ = handle.shared.close();
+            }
+            Ok(code)
+        },
+    )?;
+    conn.create_scalar_function(
+        "honker_update_watcher_close",
+        1,
+        FunctionFlags::SQLITE_UTF8,
+        |ctx| {
+            let id: i64 = ctx.get(0)?;
+            if let Some(handle) = SQL_WATCHERS.lock().unwrap().remove(&(id as u64)) {
+                handle.shared.unsubscribe(handle.sub_id);
+                let _ = handle.shared.close();
+            }
+            Ok(1)
+        },
+    )?;
+    Ok(())
+}
+
+unsafe fn set_error_msg(
+    pz_err_msg: *mut *mut c_char,
+    p_api: *mut ffi::sqlite3_api_routines,
+    message: &str,
+) {
+    if pz_err_msg.is_null() || p_api.is_null() {
+        return;
+    }
+    let Some(malloc) = (unsafe { (*p_api).malloc }) else {
+        return;
+    };
+    let len = match message.len().checked_add(1) {
+        Some(len) if c_int::try_from(len).is_ok() => len,
+        _ => return,
+    };
+    let ptr = unsafe { malloc(len as c_int) }.cast::<c_char>();
+    if ptr.is_null() {
+        return;
+    }
+    unsafe {
+        ptr::copy_nonoverlapping(message.as_ptr().cast::<c_char>(), ptr, message.len());
+        *ptr.add(message.len()) = 0;
+        *pz_err_msg = ptr;
+    }
+}
+
+unsafe fn extension_init2(
+    db: *mut ffi::sqlite3,
+    pz_err_msg: *mut *mut c_char,
+    p_api: *mut ffi::sqlite3_api_routines,
+) -> c_int {
+    if p_api.is_null() {
+        return ffi::SQLITE_ERROR;
+    }
+    let result = unsafe { ffi::rusqlite_extension_init2(p_api) }
+        .map_err(Error::from)
+        .and_then(|()| unsafe { Connection::from_handle(db) })
+        .and_then(extension_init);
+    match result {
+        Ok(true) => ffi::SQLITE_OK_LOAD_PERMANENTLY,
+        Ok(false) => ffi::SQLITE_OK,
+        Err(err) => {
+            unsafe { set_error_msg(pz_err_msg, p_api, &err.to_string()) };
+            ffi::SQLITE_ERROR
+        }
+    }
+}
+
+/// SQLite entry point. Name must match `sqlite3_<extname>_init`; SQLite
+/// derives `<extname>` from the filename — stripping the `lib` prefix
+/// and any non-alphabetic characters:
+/// `libhonker_ext.dylib` -> `honker_ext` -> `honkerext`
+/// -> `sqlite3_honkerext_init`.
+///
+/// # Safety
+/// Called by SQLite. All pointers are SQLite-owned.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn sqlite3_honkerext_init(
+    db: *mut ffi::sqlite3,
+    pz_err_msg: *mut *mut c_char,
+    p_api: *mut ffi::sqlite3_api_routines,
+) -> c_int {
+    match catch_unwind(AssertUnwindSafe(|| unsafe {
+        extension_init2(db, pz_err_msg, p_api)
+    })) {
+        Ok(code) => code,
+        Err(payload) => {
+            let err = panic_error(payload);
+            unsafe { set_error_msg(pz_err_msg, p_api, &err.to_string()) };
+            ffi::SQLITE_ERROR
+        }
+    }
+}
+
+pub struct HonkerWatcherHandle {
+    shared: Arc<honker_core::SharedUpdateWatcher>,
+    sub_id: u64,
+    rx: Receiver<()>,
+}
+
+unsafe fn cstr_to_string(ptr: *const c_char) -> std::result::Result<Option<String>, String> {
+    if ptr.is_null() {
+        return Ok(None);
+    }
+    let s = unsafe { CStr::from_ptr(ptr) }
+        .to_str()
+        .map_err(|e| format!("invalid UTF-8: {e}"))?;
+    if s.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(s.to_string()))
+    }
+}
+
+unsafe fn write_error(buf: *mut c_char, len: usize, message: &str) {
+    if buf.is_null() || len == 0 {
+        return;
+    }
+    let bytes = message.as_bytes();
+    let copy_len = bytes.len().min(len.saturating_sub(1));
+    unsafe {
+        ptr::copy_nonoverlapping(bytes.as_ptr().cast::<c_char>(), buf, copy_len);
+        *buf.add(copy_len) = 0;
+    }
+}
+
+/// Open a core-backed update watcher over `db_path`.
+///
+/// Returns null on error and writes a NUL-terminated diagnostic into
+/// `err_buf` when provided. `backend` accepts the same exact aliases as
+/// `honker_core::WatcherBackend::parse`; null / empty means polling.
+///
+/// # Safety
+/// All pointers must be valid NUL-terminated strings when non-null.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn honker_watcher_open(
+    db_path: *const c_char,
+    backend: *const c_char,
+    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())?;
+        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()
+        }
+    }
+}
+
+/// Wait for the next database update.
+///
+/// Returns:
+/// * `1` when an update was observed
+/// * `0` on timeout
+/// * `-1` when the watcher/subscription has closed or died
+/// * `-2` if this function catches an internal panic
+///
+/// # Safety
+/// `handle` must be a pointer returned by `honker_watcher_open` and not
+/// yet passed to `honker_watcher_close`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn honker_watcher_wait(
+    handle: *mut HonkerWatcherHandle,
+    timeout_ms: u64,
+) -> c_int {
+    if handle.is_null() {
+        return -1;
+    }
+    match catch_unwind(AssertUnwindSafe(|| {
+        let handle = unsafe { &mut *handle };
+        match handle.rx.recv_timeout(Duration::from_millis(timeout_ms)) {
+            Ok(()) => 1,
+            Err(RecvTimeoutError::Timeout) => 0,
+            Err(RecvTimeoutError::Disconnected) => -1,
+        }
+    })) {
+        Ok(code) => code,
+        Err(_) => -2,
+    }
+}
+
+/// Close a watcher opened by `honker_watcher_open`.
+///
+/// # Safety
+/// `handle` must be null or a pointer returned by `honker_watcher_open`.
+/// Passing the same non-null pointer twice is undefined behavior.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn honker_watcher_close(handle: *mut HonkerWatcherHandle) {
+    if handle.is_null() {
+        return;
+    }
+    let handle = unsafe { Box::from_raw(handle) };
+    handle.shared.unsubscribe(handle.sub_id);
+    let _ = handle.shared.close();
+}

data/honker.gemspec

@@ -21,10 +21,33 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"]    = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/russellromney/honker"
   spec.metadata["documentation_uri"] = "https://honker.dev/"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
-  spec.files = Dir.glob("lib/**/*") + %w[honker.gemspec README.md LICENSE LICENSE-MIT LICENSE-APACHE]
+  # HONKER_GEM_PLATFORM is set by the release workflow when building a
+  # precompiled platform gem: it bundles the prebuilt extension next to
+  # the Ruby source in lib/honker/. Without it `gem build` produces the
+  # generic gem, which ships the Rust crate source and compiles the
+  # extension on install (see ext/honker/extconf.rb).
+  gem_platform = ENV.fetch("HONKER_GEM_PLATFORM", nil)
+  generic_gem = gem_platform.nil? || gem_platform.empty?
+  spec.platform = gem_platform unless generic_gem
+
+  extension_files = Dir.glob("lib/honker/{libhonker_ext.*,honker_ext.dll}")
+  ruby_files = Dir.glob("lib/**/*") - extension_files
+  base_files = ruby_files +
+    %w[honker.gemspec README.md LICENSE LICENSE-MIT LICENSE-APACHE]
+
+  if generic_gem
+    spec.extensions = ["ext/honker/extconf.rb"]
+    spec.files = base_files + Dir.glob("ext/**/*").select { |f| File.file?(f) }
+  else
+    spec.files = base_files + extension_files
+  end
   spec.require_paths = ["lib"]
 
+  # CoreWatcher calls into the extension over Fiddle. Declared
+  # explicitly because fiddle stopped being a default gem in Ruby 3.5.
+  spec.add_dependency "fiddle", "~> 1.0"
   # 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

data/lib/honker/README.md

@@ -0,0 +1,28 @@
+# lib/honker
+
+Ruby source for the `honker` gem.
+
+## The bundled SQLite extension
+
+Released **platform gems** also ship the prebuilt Honker SQLite loadable
+extension in this directory. It is not checked into the source
+repository: it is a build artifact, gitignored, copied in at release
+time by `scripts/copy-ruby-extension.sh` and verified by
+`scripts/proof/check-ruby-gem.rb`.
+
+When it is present, `Honker::Database.new` finds and loads it
+automatically, so a platform gem needs no `extension_path:`.
+
+| Gem platform    | Bundled extension file |
+| --------------- | ---------------------- |
+| `x86_64-linux`  | `libhonker_ext.so`     |
+| `aarch64-linux` | `libhonker_ext.so`     |
+| `arm64-darwin`  | `libhonker_ext.dylib`  |
+
+The artifact name follows the target OS: `libhonker_ext.so` on Linux,
+`libhonker_ext.dylib` on macOS, and `honker_ext.dll` on Windows.
+
+The **generic gem** (used on every other platform, and for `github:`
+installs) ships no prebuilt extension. Instead it bundles the Rust crate
+source under `ext/honker/` and compiles the extension into this
+directory on install, which needs a [Rust toolchain](https://rustup.rs).

data/lib/honker/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Honker
+  class Railtie < ::Rails::Railtie
+    config.after_initialize do
+      Honker.bootstrap(ActiveRecord::Base.connection)
+    end
+  end
+end

data/lib/honker/scheduler.rb

@@ -79,6 +79,65 @@ module Honker
       @db.db.get_first_row("SELECT honker_scheduler_soonest()")[0]
     end
 
+    # ---- Phase Mantle: lifecycle methods ----
+
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+
+    # Pause a registered schedule. Returns true if a row was paused;
+    # false if missing or already paused. Idempotent.
+    def pause(name)
+      n = @db.db.get_first_row(
+        "SELECT honker_scheduler_pause(?)", [name],
+      )[0]
+      @db.mark_updated if n.positive?
+      n.positive?
+    end
+
+    # Resume a paused schedule. Returns true if a row was resumed.
+    def resume(name)
+      n = @db.db.get_first_row(
+        "SELECT honker_scheduler_resume(?)", [name],
+      )[0]
+      @db.mark_updated if n.positive?
+      n.positive?
+    end
+
+    # Return every registered schedule with current state. Each entry
+    # is a Hash with: name, queue, cron_expr, payload (JSON string),
+    # priority, expires_s, next_fire_at, enabled.
+    def list
+      raw = @db.db.get_first_row("SELECT honker_scheduler_list()")[0]
+      return [] if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    end
+
+    # Mutate fields in place. Pass only the kwargs you want changed
+    # (omitting a kwarg leaves the field alone). `payload: nil`
+    # writes JSON null. Cron change recomputes next_fire_at from now.
+    # Returns true iff a row was updated.
+    def update(name, schedule: UNSET, cron: UNSET, payload: UNSET, priority: UNSET, expires_s: UNSET)
+      expr = nil
+      expr = schedule if schedule != UNSET
+      expr = cron if expr.nil? && cron != UNSET
+
+      payload_arg = (payload == UNSET) ? nil : JSON.dump(payload)
+      priority_arg = (priority == UNSET) ? nil : priority
+      touch_expires = (expires_s == UNSET) ? 0 : 1
+      expires_arg = (expires_s == UNSET) ? nil : expires_s
+
+      any_field = !expr.nil? || payload != UNSET || priority != UNSET || expires_s != UNSET
+      return false unless any_field
+
+      n = @db.db.get_first_row(
+        "SELECT honker_scheduler_update(?, ?, ?, ?, ?, ?)",
+        [name, expr, payload_arg, priority_arg, expires_arg, touch_expires],
+      )[0]
+      @db.mark_updated if n.positive?
+      n.positive?
+    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-

data/lib/honker/version.rb

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

data/lib/honker.rb

@@ -19,6 +19,7 @@
 
 require "json"
 require "fiddle"
+require "rbconfig"
 require "sqlite3"
 
 require_relative "honker/version"
@@ -26,8 +27,91 @@ require_relative "honker/transaction"
 require_relative "honker/stream"
 require_relative "honker/scheduler"
 require_relative "honker/lock"
+require_relative "honker/railtie" if defined?(::Rails::Railtie)
 
 module Honker
+  # Honker's error class, raised by ExtensionResolver and CoreWatcher.
+  class Error < StandardError; end
+
+  # Resolves the path to the Honker SQLite loadable extension. Platform
+  # gems ship it bundled in lib/honker/; an explicit path and the
+  # HONKER_EXTENSION_PATH override take precedence.
+  class ExtensionResolver
+    def initialize(env: ENV.fetch("HONKER_EXTENSION_PATH", nil), bundled: nil)
+      @env = env
+      @bundled = bundled || File.expand_path("honker/#{extension_filename}", __dir__)
+    end
+
+    # Returns the extension path: an explicit `extension_path`, else
+    # HONKER_EXTENSION_PATH, else the bundled extension. Raises
+    # Honker::Error when HONKER_EXTENSION_PATH or the bundled extension
+    # is missing.
+    def resolve(extension_path = nil)
+      return extension_path unless extension_path.nil?
+      return env_extension unless env.nil? || env.empty?
+
+      path = bundled
+      return path if File.file?(path)
+
+      raise Error, "Honker SQLite extension not found at #{path}; " \
+                   "set HONKER_EXTENSION_PATH or pass extension_path:"
+    end
+
+    private
+
+    attr_reader :env, :bundled
+
+    def env_extension
+      return env if File.file?(env)
+
+      raise Error, "HONKER_EXTENSION_PATH does not exist: #{env}"
+    end
+
+    def extension_filename
+      case RbConfig::CONFIG.fetch("host_os")
+      when /mswin|mingw|cygwin/ then "honker_ext.dll"
+      when /darwin/ then "libhonker_ext.dylib"
+      else "libhonker_ext.so"
+      end
+    end
+  end
+
+  # Resolve the bundled (or overridden) extension path without naming
+  # ExtensionResolver — useful for `database.yml` ERB and tooling.
+  def self.extension_path(override = nil)
+    ExtensionResolver.new.resolve(override)
+  end
+
+  # Load the Honker extension onto a raw SQLite3::Database. Encapsulates
+  # the enable_load_extension(true)/load/enable_load_extension(false)
+  # sequence so the toggle-off can't be forgotten.
+  def self.load_extension(sqlite_conn, extension_path: nil)
+    resolved = ExtensionResolver.new.resolve(extension_path)
+    sqlite_conn.enable_load_extension(true)
+    sqlite_conn.load_extension(resolved)
+  ensure
+    sqlite_conn.enable_load_extension(false)
+  end
+
+  # Run honker_bootstrap() on the connection. Idempotent. Separated from
+  # load_extension so production users can opt to bootstrap from a
+  # migration instead of every connect.
+  def self.bootstrap(sqlite_conn)
+    sqlite_conn.execute("SELECT honker_bootstrap()")
+  end
+
+  # Convenience: load the extension then bootstrap. The one-liner most
+  # ORM integrations reach for.
+  def self.setup(sqlite_conn, extension_path: nil, bootstrap: true)
+    load_extension(sqlite_conn, extension_path: extension_path)
+    self.bootstrap(sqlite_conn) if bootstrap
+  end
+
+  # Returns a Proc suitable for Sequel/Rom/Hanami `after_connect:`.
+  def self.sequel_after_connect(extension_path: nil, bootstrap: true)
+    proc { |conn| setup(conn, extension_path: extension_path, bootstrap: bootstrap) }
+  end
+
   class CoreWatcher
     def initialize(db_path, extension_path, backend)
       @lib = Fiddle.dlopen(extension_path)
@@ -86,21 +170,23 @@ module Honker
   class Database
     attr_reader :db
 
-    def initialize(path, extension_path:, watcher_backend: nil)
+    def initialize(path, extension_path: nil, watcher_backend: nil,
+                   extension_resolver: ExtensionResolver.new)
       unless watcher_backend.nil? || watcher_backend.is_a?(String)
         raise ArgumentError, "unknown watcher backend"
       end
 
+      resolved_extension = extension_resolver.resolve(extension_path)
       @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.load_extension(resolved_extension)
       @db.enable_load_extension(false)
       @db.execute_batch(DEFAULT_PRAGMAS)
       @db.execute("SELECT honker_bootstrap()")
-      @watcher = CoreWatcher.new(path, extension_path, watcher_backend)
+      @watcher = CoreWatcher.new(path, resolved_extension, watcher_backend)
     end
 
     def close
@@ -348,6 +434,28 @@ module Honker
         [job_id, worker_id, extend_s],
       )[0] == 1
     end
+
+    # Delete a pending or processing job by id. Returns true iff a row
+    # was removed. Idempotent on missing.
+    #
+    # IMPORTANT: cancel does NOT interrupt a worker currently running
+    # the handler. It invalidates the worker's claim — its next
+    # ack/heartbeat returns false. If you need the handler to actually
+    # halt, build that signal in your app.
+    def cancel(job_id)
+      n = @db.db.get_first_row("SELECT honker_cancel(?)", [job_id])[0]
+      @db.mark_updated if n.positive?
+      n.positive?
+    end
+
+    # Read a single job row by id. Returns a Hash with the row fields,
+    # or nil if the job has been ack'd, dead'd, or never existed.
+    def get_job(job_id)
+      raw = @db.db.get_first_row("SELECT honker_get_job(?)", [job_id])[0]
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    end
   end
 
   class Outbox