wurk 0.0.1

data/lib/wurk/leader.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'socket'
+require_relative 'component'
+
+module Wurk
+  # Cluster leader election via Redis `SET NX EX`. Single-leader-per-cluster
+  # is best-effort (not Raft): a partitioned ex-leader can briefly co-exist
+  # with a new one until the TTL expires. Callers that need strict mutual
+  # exclusion must idempotency-guard their writes (see `#token`).
+  #
+  # Wire-compat: the cluster lock lives at `dear-leader` (STRING, EX≈30s)
+  # holding the `<hostname>:<pid>:<process_nonce>` identity. Each fresh
+  # gain also pulls a monotonic fencing token via `INCR leader-token`,
+  # exposed on `#token`. Wurk goes a small step beyond Sidekiq Enterprise
+  # (which deliberately does not expose fencing) so downstream code that
+  # *can* benefit from a guard has one available; the token is best-effort
+  # too — it is never re-read on subsequent acquires, only on transitions.
+  #
+  # Cadence per spec: renew every 15s while leader, recheck every 60s as
+  # follower, lock TTL 30s. Opt out a process from campaigning entirely
+  # with `WURK_LEADER=false` (useful for hot-standby pools).
+  #
+  # Spec: docs/target/sidekiq-ent.md §6.
+  class Leader
+    DEFAULT_KEY = 'dear-leader'
+    TOKEN_KEY = 'leader-token'
+    DEFAULT_TTL = 30
+    DEFAULT_RENEW_INTERVAL = 15
+    DEFAULT_FOLLOWER_INTERVAL = 60
+    OPT_OUT_ENV = 'WURK_LEADER'
+    THREAD_NAME = 'wurk-leader'
+
+    attr_reader :key, :ttl, :owner, :token, :config
+
+    def initialize(config: nil, key: DEFAULT_KEY, ttl: DEFAULT_TTL, # rubocop:disable Metrics/ParameterLists
+                   renew_interval: DEFAULT_RENEW_INTERVAL,
+                   follower_interval: DEFAULT_FOLLOWER_INTERVAL,
+                   pool: nil, owner: nil)
+      @config = config
+      @key = key
+      @ttl = ttl
+      @renew_interval = renew_interval
+      @follower_interval = follower_interval
+      @pool = pool
+      @owner = owner || cluster_identity
+      @held = false
+      @token = nil
+      @thread = nil
+      @done = false
+      @mutex = ::Mutex.new
+      @sleeper = ::ConditionVariable.new
+    end
+
+    # `WURK_LEADER=false` makes `acquire` a no-op and `leader?` permanently
+    # false; the renewal thread also refuses to start. Useful for hot-
+    # standby pools that must never campaign.
+    def disabled?
+      ENV[OPT_OUT_ENV].to_s.downcase == 'false'
+    end
+
+    # SET NX EX. If the key already holds *our* owner string (rare — same
+    # process re-entering after a hiccup), refresh via EXPIRE so leadership
+    # doesn't lapse. On any follower → leader transition, INCR the global
+    # `leader-token` so the new token is strictly greater than every prior
+    # leader's, then dispatch the `:leader` lifecycle event.
+    def acquire # rubocop:disable Naming/PredicateMethod
+      return false if disabled?
+
+      transition = run_set_or_refresh
+      return false unless transition
+
+      if transition == :gained
+        @token = redis_call { |c| c.call('INCR', TOKEN_KEY) }
+        dispatch_leader_event
+      end
+      true
+    end
+
+    # CAS DEL — only drop the key if we still own it, otherwise a stale
+    # release would yank leadership from whichever follower took over.
+    def release
+      redis_call do |c|
+        c.call('DEL', @key) if c.call('GET', @key) == @owner
+      end
+      @held = false
+      @token = nil
+      nil
+    end
+
+    def leader?
+      @held
+    end
+
+    # Spawns the periodic re-election thread. Idempotent. While leader,
+    # the loop re-acquires (refreshing TTL) every `renew_interval`; while
+    # follower, it polls every `follower_interval`. Caller must invoke
+    # `stop` for orderly shutdown — the thread also releases its lock on
+    # exit.
+    def start
+      return nil if disabled?
+
+      @mutex.synchronize do
+        return @thread if @thread
+
+        @done = false
+      end
+      @thread = spawn_loop_thread
+    end
+
+    def stop
+      @mutex.synchronize do
+        @done = true
+        @sleeper.signal
+      end
+      @thread&.join
+      @thread = nil
+      release
+    end
+
+    def running?
+      !@thread.nil? && @thread.alive?
+    end
+
+    private
+
+    # Returns `:gained` on first acquisition, `:held` on renewal, or `nil`
+    # if another process currently holds the key. Sets `@held` accordingly
+    # so `leader?` reflects the latest state regardless of branch.
+    def run_set_or_refresh
+      redis_call do |c|
+        result = c.call('SET', @key, @owner, 'NX', 'EX', @ttl)
+        if result == 'OK'
+          outcome = @held ? :held : :gained
+          @held = true
+          return outcome
+        end
+
+        if c.call('GET', @key) == @owner
+          c.call('EXPIRE', @key, @ttl)
+          outcome = @held ? :held : :gained
+          @held = true
+          return outcome
+        end
+
+        @held = false
+        @token = nil
+        nil
+      end
+    end
+
+    def dispatch_leader_event
+      return if @config.nil?
+      return unless @config.respond_to?(:[])
+
+      bucket = @config[:lifecycle_events]&.[](:leader)
+      return if bucket.nil? || bucket.empty?
+
+      bucket.each { |hook| invoke_hook(hook) }
+    end
+
+    def invoke_hook(hook)
+      hook.call
+    rescue StandardError => e
+      @config.handle_exception(e, event: :leader) if @config.respond_to?(:handle_exception)
+    end
+
+    def redis_call(&)
+      if @pool
+        @pool.with(&)
+      elsif @config
+        @config.redis(&)
+      else
+        Wurk.redis(&)
+      end
+    end
+
+    # Matches `Wurk::Component#identity` so `ProcessSet::Process#leader?`
+    # (which compares `dear-leader == process.identity`) sees a match.
+    def cluster_identity
+      "#{hostname}:#{::Process.pid}:#{Component::PROCESS_NONCE}"
+    end
+
+    def hostname
+      ENV['DYNO'] || ::Socket.gethostname
+    rescue StandardError
+      'localhost'
+    end
+
+    def spawn_loop_thread
+      t = Thread.new { run_loop }
+      t.name = THREAD_NAME
+      t.report_on_exception = false
+      t
+    end
+
+    def run_loop
+      until done?
+        tick_once
+        wait_next
+      end
+      release
+    end
+
+    def tick_once
+      acquire
+    rescue StandardError => e
+      @config.handle_exception(e, context: THREAD_NAME) if @config.respond_to?(:handle_exception)
+    end
+
+    def wait_next
+      interval = @held ? @renew_interval : @follower_interval
+      @mutex.synchronize { @sleeper.wait(@mutex, interval) unless @done }
+    end
+
+    def done?
+      @mutex.synchronize { @done }
+    end
+  end
+end

data/lib/wurk/limiter/base.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+require 'securerandom'
+
+module Wurk
+  module Limiter
+    # Shared base for every limiter type. Holds the public introspection
+    # contract documented in §1.5 — name / type / options / size / status /
+    # reset / delete plus the `within_limit(...) { ... }` block. Subclasses
+    # override the acquire path and the per-type metric/size methods.
+    #
+    # `status` is uniform across types (#16): `{ used:, limit:, reset_at:,
+    # available? }`. Subclasses supply the three values via `build_status`;
+    # Concurrent additionally merges its metric counters.
+    class Base
+      attr_reader :name, :options
+
+      # `register:` defaults true so constructing a limiter publishes its
+      # metadata + `lmtr-list` membership. The dashboard reconstructs limiters
+      # purely to read `status` on a GET, so it passes `register: false` to
+      # keep introspection side-effect-free.
+      def initialize(name, register: true, **options)
+        unless name.is_a?(String) && NAME_PATTERN.match?(name)
+          raise ArgumentError, "limiter name must match #{NAME_PATTERN.inspect} (got #{name.inspect})"
+        end
+
+        ttl = options[:ttl] || DEFAULT_TTL
+        # Spec §1.2: ttl floor of 24h. Anything tighter risks losing the
+        # metadata hash mid-job and orphaning slots that read it.
+        raise ArgumentError, 'ttl must be >= 86_400' if ttl < 86_400
+
+        @name = name.dup.freeze
+        @options = options
+        register! if register
+      end
+
+      def type
+        raise NotImplementedError
+      end
+
+      def within_limit(**, &)
+        raise NotImplementedError
+      end
+
+      def size
+        0
+      end
+
+      # Uniform across types (#16). Subclasses override to fill in real
+      # numbers; the default reports an idle, unlimited shape.
+      def status
+        build_status(used: 0, limit: nil, reset_at: nil)
+      end
+
+      def reset
+        Wurk::Limiter.redis do |c|
+          state_keys.each { |k| c.call('DEL', k) }
+        end
+      end
+
+      def delete
+        Wurk::Limiter.redis do |c|
+          (state_keys + [meta_key]).each { |k| c.call('DEL', k) }
+          c.call('SREM', LIST_KEY, @name)
+        end
+      end
+
+      # Stable fingerprint for the limiter — Sidekiq 8.0+ switched from
+      # SHA1 → SHA256 (~10% larger encoding). Web UI groups limiters by
+      # this so that interpolated names (`stripe-#{user_id}`) get a single
+      # row per shape.
+      def fingerprint
+        @fingerprint ||= Digest::SHA256.hexdigest("#{type}|#{@name}|#{JSON.dump(serializable_options)}")
+      end
+
+      protected
+
+      # Assemble the uniform status hash. `available?` is derived: an
+      # unlimited (nil) limit is always available; otherwise headroom remains
+      # while `used < limit`. `reset_at` is an epoch-seconds Float (or nil
+      # when the type has no clock-driven reset).
+      def build_status(used:, limit:, reset_at:)
+        { used: used, limit: limit, reset_at: reset_at,
+          available?: limit.nil? || used < limit }
+      end
+
+      def meta_key
+        "lmtr:#{@name}"
+      end
+
+      def state_keys
+        []
+      end
+
+      def serializable_options
+        @options.transform_values do |v|
+          case v
+          when Proc then '<proc>'
+          when Symbol, Numeric, String, true, false, nil then v
+          else v.to_s
+          end
+        end
+      end
+
+      def register!
+        Wurk::Limiter.redis do |c|
+          c.call('SADD', LIST_KEY, @name)
+          c.call(
+            'HSET', meta_key,
+            'type', type.to_s,
+            'options', JSON.dump(serializable_options),
+            'fingerprint', fingerprint
+          )
+          c.call('EXPIRE', meta_key, @options[:ttl])
+        end
+      end
+
+      def ttl
+        @options[:ttl]
+      end
+
+      # Stable random slot id (Concurrent) / nonce (Window). 16 hex chars
+      # = 8 bytes — wide enough to avoid collision under any realistic
+      # burst and short enough to keep ZSET memory bounded.
+      def random_id
+        SecureRandom.hex(8)
+      end
+
+      def lua(name, keys:, argv:)
+        Wurk::Limiter.redis do |c|
+          Wurk::Lua::Loader.eval_cached(c, name, keys: keys, argv: argv)
+        end
+      end
+    end
+  end
+end

data/lib/wurk/limiter/bucket.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Wurk
+  module Limiter
+    # Cardinal-boundary counter. Reset at the top of the unit (00:00 of
+    # minute/hour/day). On exhaustion sleep until next boundary, retry,
+    # OverLimit if that exceeds wait_timeout.
+    class Bucket < Base
+      def type = :bucket
+
+      def initialize(name, **options)
+        # Eager interval validation so a typo in `:fortnight` blows up at boot,
+        # not at first call. Lazy validation defers failures to runtime.
+        Limiter.interval_seconds(options[:interval], allow_integer: false)
+        super
+      end
+
+      def size
+        Wurk::Limiter.redis { |c| (c.call('GET', epoch_key) || '0').to_i }
+      end
+
+      # used = this period's count; limit = count; reset_at = the next
+      # cardinal boundary, when the counter rolls back to zero (#16).
+      def status
+        build_status(used: size, limit: @options[:count], reset_at: next_boundary)
+      end
+
+      def within_limit(used: 1, &block)
+        raise ArgumentError, 'block required' unless block
+
+        deadline = ::Time.now.to_f + @options[:wait_timeout]
+        loop do
+          ok, _current, secs_to_next = acquire(used)
+          return block.call if ok.to_i == 1
+
+          remaining = deadline - ::Time.now.to_f
+          raise OverLimit, self if remaining <= 0
+
+          sleep [remaining, secs_to_next.to_f, 0.05].compact.min.clamp(0.0, remaining)
+        end
+      end
+
+      protected
+
+      def state_keys
+        # Bucket keys are per-epoch and self-expiring; reset wipes the
+        # current epoch, the only one a caller could care about. Older
+        # epochs already EXPIRE'd.
+        epoch = ::Time.now.to_i / interval_seconds
+        ["lmtr-b:#{@name}:#{epoch}"]
+      end
+
+      private
+
+      def epoch_index
+        ::Time.now.to_i / interval_seconds
+      end
+
+      def epoch_key
+        "lmtr-b:#{@name}:#{epoch_index}"
+      end
+
+      def next_boundary
+        (epoch_index + 1).to_f * interval_seconds
+      end
+
+      def interval_seconds
+        @interval_seconds ||= Limiter.interval_seconds(@options[:interval], allow_integer: false)
+      end
+
+      def acquire(used)
+        lua(:limiter_bucket_acquire,
+            keys: ["lmtr-b:#{@name}"],
+            argv: [@options[:count], interval_seconds, used, ttl])
+      end
+    end
+  end
+end

data/lib/wurk/limiter/concurrent.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Wurk
+  module Limiter
+    # Atomic slot acquisition in a ZSET. Score = expiry epoch; the acquire
+    # script first evicts expired slots (bumping the `reclaimed` metric)
+    # then ZADDs if there's headroom.
+    #
+    # On exhaustion: spin loop with backoff. The spec says "blocks via
+    # Redis stream XREAD" — that's a perf optimization; the visible
+    # behavior is identical: blocks up to `wait_timeout` then OverLimit
+    # (or silent return for `policy: :ignore`).
+    class Concurrent < Base
+      WAIT_SLEEP = 0.05
+
+      METRIC_FIELDS = %w[held held_time immediate waited wait_time overages reclaimed].freeze
+
+      def type = :concurrent
+
+      def size
+        Wurk::Limiter.redis { |c| c.call('ZCARD', state_key).to_i }
+      end
+
+      # Uniform `{ used:, limit:, reset_at:, available? }` (#16) merged with
+      # the concurrent-only metric counters (§1.5) the dashboard already
+      # renders. Slots free on release rather than on a clock, so `reset_at`
+      # is the soonest in-flight slot expiry (a worst-case "available by"),
+      # or nil when idle.
+      def status
+        used = size
+        build_status(used: used, limit: @options[:limit], reset_at: soonest_expiry)
+          .merge(metrics)
+      end
+
+      def within_limit(&block)
+        raise ArgumentError, 'block required' unless block
+
+        started = monotime
+        deadline = started + @options[:wait_timeout]
+        slot = random_id
+        acquired_at = nil
+        loop do
+          result = acquire(slot)
+          if result[0].to_i == 1
+            acquired_at = monotime
+            break
+          end
+
+          return if @options[:policy] == :ignore
+
+          remaining = deadline - monotime
+          if remaining <= 0
+            bump_counter('overages')
+            raise OverLimit, self
+          end
+
+          sleep [remaining, WAIT_SLEEP].min
+        end
+
+        begin
+          incr_immediate_or_waited(acquired_at - started)
+          block.call
+        ensure
+          release(slot)
+          bump_counter('held_time', (monotime - acquired_at).to_i) if acquired_at
+        end
+      end
+
+      protected
+
+      def state_keys
+        [state_key, stats_key]
+      end
+
+      private
+
+      def metrics
+        h = Wurk::Limiter.redis { |c| c.call('HGETALL', stats_key) }
+        # redis-client returns either a flat array or a hash depending on
+        # the server version — normalize once so callers always see a hash.
+        h = h.each_slice(2).to_h if h.is_a?(Array)
+        METRIC_FIELDS.to_h { |k| [k, (h[k] || '0').to_i] }
+      end
+
+      # Lowest slot expiry epoch (the next slot to free), or nil when empty.
+      def soonest_expiry
+        row = Wurk::Limiter.redis { |c| c.call('ZRANGE', state_key, 0, 0, 'WITHSCORES') }
+        row && !row.empty? ? row[1].to_f : nil
+      end
+
+      def state_key
+        "lmtr-cs:#{@name}"
+      end
+
+      def stats_key
+        "lmtr-stats:#{@name}"
+      end
+
+      def acquire(slot)
+        lua(:limiter_concurrent_acquire,
+            keys: [state_key, stats_key],
+            argv: [@options[:limit], @options[:lock_timeout], slot, ttl])
+      end
+
+      def release(slot)
+        lua(:limiter_concurrent_release, keys: [state_key], argv: [slot])
+      end
+
+      def bump_counter(field, by = 1)
+        Wurk::Limiter.redis do |c|
+          c.call('HINCRBY', stats_key, field, by)
+          c.call('EXPIRE', stats_key, ttl)
+        end
+      end
+
+      def incr_immediate_or_waited(elapsed)
+        if elapsed < WAIT_SLEEP
+          bump_counter('immediate')
+        else
+          bump_counter('waited')
+          bump_counter('wait_time', elapsed.to_i)
+        end
+      end
+
+      def monotime
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/wurk/limiter/leaky.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Wurk
+  module Limiter
+    # Leaky bucket: drain rate = bucket_size / drain ops/sec. Stored as a
+    # HASH of {level, last} — Lua compares level vs bucket_size after
+    # leaking elapsed * drain_per_sec.
+    class Leaky < Base
+      WAIT_SLEEP = 0.05
+
+      def type = :leaky
+
+      def size
+        h = Wurk::Limiter.redis { |c| c.call('HGET', state_key, 'level') }
+        h.to_f
+      end
+
+      # used = current fill level; limit = bucket_size; reset_at = when the
+      # steady drip frees a slot (only meaningful while full), else nil (#16).
+      def status
+        level = size
+        cap = @options[:bucket_size]
+        reset_at = level >= cap ? ::Time.now.to_f + ((level - cap + 1) / drain_per_sec) : nil
+        build_status(used: level, limit: cap, reset_at: reset_at)
+      end
+
+      def within_limit(&block)
+        raise ArgumentError, 'block required' unless block
+
+        deadline = ::Time.now.to_f + @options[:wait_timeout]
+        loop do
+          ok, _level = acquire
+          return block.call if ok.to_i == 1
+
+          remaining = deadline - ::Time.now.to_f
+          raise OverLimit, self if remaining <= 0
+
+          sleep [remaining, WAIT_SLEEP].min
+        end
+      end
+
+      protected
+
+      def state_keys
+        [state_key]
+      end
+
+      private
+
+      def state_key
+        "lmtr-l:#{@name}"
+      end
+
+      def drain_interval_seconds
+        case @options[:drain]
+        when Symbol
+          Limiter.interval_seconds(@options[:drain], allow_integer: false)
+        when Integer
+          raise ArgumentError, "drain must be > 0 (got #{@options[:drain]})" unless @options[:drain].positive?
+
+          @options[:drain]
+        else
+          raise ArgumentError, "drain must be Symbol or Integer (got #{@options[:drain].class})"
+        end
+      end
+
+      # bucket_size / drain → ops per second. A zero/negative bucket_size would
+      # silently produce a non-positive rate (and a 1/0 in `status` reset_at);
+      # fail fast at the boundary so callers see the bad config, not a NaN.
+      def drain_per_sec
+        @drain_per_sec ||= begin
+          rate = @options[:bucket_size].to_f / drain_interval_seconds
+          unless rate.positive?
+            raise ArgumentError,
+                  "drain_per_sec must be > 0 (bucket_size=#{@options[:bucket_size]}, drain=#{@options[:drain]})"
+          end
+
+          rate
+        end
+      end
+
+      def acquire
+        lua(:limiter_leaky_acquire,
+            keys: [state_key],
+            argv: [@options[:bucket_size], drain_per_sec, ttl])
+      end
+    end
+  end
+end