honker 0.3.0-aarch64-linux

data/lib/honker/scheduler.rb

@@ -0,0 +1,249 @@
+# 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
+
+  # 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.
+  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
+    UPDATE_POLL_S = 0.05
+
+    def initialize(db)
+      @db = db
+    end
+
+    # 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, expr, JSON.dump(payload), priority, expires_s],
+      )
+      @db.mark_updated
+      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].tap { @db.mark_updated }
+    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
+
+    # ---- 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-
+    # 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
+          wait_for_update_or_timeout(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
+
+    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
+
+        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
+
+    def monotonic_now
+      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(?, ?, ?)",
+        [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.3.0"
+end