wurk 0.0.1

data/lib/wurk/middleware/i18n.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative '../middleware'
+
+module Wurk
+  module Middleware
+    # Propagates `I18n.locale` from the enqueueing process to the worker.
+    # Auto-registered when this file is required: Client onto the
+    # `client_middleware` chain, Server onto `server_middleware`.
+    #
+    # No-op when the `I18n` constant is undefined (no `i18n` gem loaded);
+    # the middleware survives the absence and just passes the job through.
+    #
+    # Job hash key: `"locale"` (matches Sidekiq spec §2.2).
+    module I18n
+      class << self
+        def current_locale
+          ::I18n.locale.to_s if defined?(::I18n)
+        end
+
+        def with_locale(locale)
+          return yield unless defined?(::I18n) && locale
+
+          previous = ::I18n.locale
+          ::I18n.locale = locale
+          begin
+            yield
+          ensure
+            ::I18n.locale = previous
+          end
+        end
+      end
+
+      # Client: writes the current locale into the outgoing job hash before
+      # push. Idempotent — a caller-supplied `"locale"` is preserved.
+      # No-op when I18n isn't loaded (don't introduce a nil `"locale"` key:
+      # adding it would change the wire shape for callers without I18n).
+      class Client
+        include Wurk::Middleware::ClientMiddleware
+
+        def call(_job_class, job, _queue, _redis_pool)
+          current = I18n.current_locale
+          job['locale'] ||= current if current
+          yield
+        end
+      end
+
+      # Server: scopes the job execution to the captured locale. Restores
+      # the previous value on the way out so middleware stacking doesn't
+      # leak across jobs in the same thread.
+      class Server
+        include Wurk::Middleware::ServerMiddleware
+
+        def call(_job_instance, job, _queue, &)
+          I18n.with_locale(job['locale'], &)
+        end
+      end
+    end
+  end
+end
+
+Wurk.configuration.client_middleware.add(Wurk::Middleware::I18n::Client)
+Wurk.configuration.server_middleware.add(Wurk::Middleware::I18n::Server)

data/lib/wurk/middleware/interrupt_handler.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../middleware'
+require_relative '../job'
+require_relative '../job_retry'
+
+module Wurk
+  module Middleware
+    # Server middleware. Catches `Wurk::Job::Interrupted` raised by an
+    # IterableJob mid-iteration (or any cooperatively-cancelled job),
+    # re-pushes the job to the head of its queue so it resumes from the
+    # persisted cursor, and raises `Wurk::JobRetry::Skip` so the retry
+    # layer treats this as a clean exit rather than an error.
+    #
+    # The re-push uses LPUSH (head of queue) so the same job is the next
+    # one to be fetched after restart. The job JSON is unchanged: cursor
+    # state lives in the `it-<jid>` HASH (see IterableJob persistence),
+    # not in the payload.
+    #
+    # Auto-registered at the top of the server chain when this file is
+    # required. Top-of-chain is important: a downstream middleware must
+    # not swallow the Interrupted before we see it.
+    #
+    # Spec: docs/target/sidekiq-free.md §10.3.
+    class InterruptHandler
+      include Wurk::Middleware::ServerMiddleware
+
+      def call(_job_instance, job, queue)
+        yield
+      rescue Wurk::Job::Interrupted
+        repush(job, queue)
+        raise Wurk::JobRetry::Skip
+      end
+
+      private
+
+      def repush(job, queue)
+        payload = Wurk.dump_json(job)
+        redis_pool.with { |conn| conn.call('LPUSH', "queue:#{queue}", payload) }
+      end
+    end
+  end
+end
+
+Wurk.configuration.server_middleware.prepend(Wurk::Middleware::InterruptHandler)

data/lib/wurk/middleware/poison_pill.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../middleware'
+require_relative '../metrics/statsd'
+require_relative '../keys'
+require_relative '../dead_set'
+
+module Wurk
+  module Middleware
+    # Pro parity (§3.2): poison-pill detection for reliable-fetch orphans.
+    # When a job is recovered out of a dead process's private list, we
+    # INCR a per-jid counter at `super_fetch:recovered:<jid>` with a 72h
+    # TTL. Once the counter crosses RECOVERY_THRESHOLD (3) the next recovery
+    # is treated as a poison pill: the payload is moved to the dead set,
+    # `jobs.poison` is emitted to statsd, and recovery callbacks fire so
+    # operators can be paged.
+    #
+    # Counter key TTL is wire-compat with Sidekiq Pro — third-party tooling
+    # that watches `super_fetch:recovered:*` expects 72h.
+    #
+    # No server-middleware registration: callers are reaper / bulk_requeue
+    # paths that drive the lifecycle directly via `track!(payload, queue:)`.
+    # When that integration lands, it just calls `PoisonPill.track!` on each
+    # orphan it about to RPUSH back to the public queue.
+    module PoisonPill
+      RECOVERY_THRESHOLD = 3
+      RECOVERY_TTL = 72 * 60 * 60
+      KEY_PREFIX = 'super_fetch:recovered:'
+      DEAD_RECORD_LIMIT = 100
+
+      module_function
+
+      # Called per recovered orphan job. Returns `:poison` when the threshold
+      # was crossed and the job was killed; `:recovered` when the job is
+      # being re-pushed (caller's responsibility — we don't touch the queue
+      # here). Emits `jobs.recovered.fetch` on every call, `jobs.poison`
+      # only on the kill path.
+      #
+      # @param payload [String, Hash] the job JSON or pre-parsed hash.
+      # @param queue   [String, nil] the public queue name (without `queue:`).
+      # @return [Symbol] :recovered | :poison
+      def track!(payload, queue: nil)
+        job = parse(payload)
+        return :recovered unless job
+
+        jid = job['jid']
+        klass = job['class']
+        emit_recovered_fetch(klass, queue)
+        return :recovered if jid.nil? || jid.empty?
+
+        count = bump_counter(jid)
+        if count >= RECOVERY_THRESHOLD
+          mark_poison(payload, job, queue: queue, count: count)
+          :poison
+        else
+          :recovered
+        end
+      end
+
+      # Reads the current recovery counter without bumping it. Used by tests
+      # and dashboards; returns 0 for jobs that have never been recovered.
+      def recovery_count(jid)
+        return 0 if jid.nil? || jid.to_s.empty?
+
+        Wurk.redis { |conn| conn.call('GET', "#{KEY_PREFIX}#{jid}") }.to_i
+      end
+
+      # Resets the counter for a jid — call after a successful perform so a
+      # job that recovered twice and then completed doesn't accumulate state.
+      def clear!(jid)
+        return if jid.nil? || jid.to_s.empty?
+
+        Wurk.redis { |conn| conn.call('DEL', "#{KEY_PREFIX}#{jid}") }
+      end
+
+      # Register a callback fired when a poison pill is detected. Callbacks
+      # receive a single Hash `{jid:, klass:, count:, queue:}` — matches
+      # Sidekiq Pro's documented shape so consumers can drop in unchanged.
+      def on_poison(&block)
+        raise ArgumentError, 'block required' unless block
+
+        callbacks << block
+        block
+      end
+
+      def callbacks
+        @callbacks ||= []
+      end
+
+      # Test-only reset.
+      def reset!
+        @callbacks = []
+      end
+
+      # ---- internals --------------------------------------------------
+
+      def parse(payload)
+        case payload
+        when Hash then payload
+        when String
+          begin
+            Wurk.load_json(payload)
+          rescue ::JSON::ParserError
+            nil
+          end
+        end
+      end
+
+      def bump_counter(jid)
+        key = "#{KEY_PREFIX}#{jid}"
+        Wurk.redis do |conn|
+          count = conn.call('INCR', key).to_i
+          conn.call('EXPIRE', key, RECOVERY_TTL)
+          count
+        end
+      end
+
+      def emit_recovered_fetch(klass, queue)
+        tags = []
+        tags << "class:#{klass}" if klass
+        tags << "queue:#{queue}" if queue
+        Wurk::Metrics::Statsd.increment('jobs.recovered.fetch', tags: tags.empty? ? nil : tags)
+      end
+
+      def mark_poison(payload, job, queue:, count:)
+        emit_poison(job['class'], queue)
+        json = payload.is_a?(String) ? payload : Wurk.dump_json(job)
+        Wurk::DeadSet.new.kill(json, notify_failure: false)
+        fire_callbacks(jid: job['jid'], klass: job['class'], count: count, queue: queue)
+      end
+
+      def emit_poison(klass, queue)
+        tags = []
+        tags << "class:#{klass}" if klass
+        tags << "queue:#{queue}" if queue
+        Wurk::Metrics::Statsd.increment('jobs.poison', tags: tags.empty? ? nil : tags)
+      end
+
+      def fire_callbacks(pill)
+        callbacks.each do |cb|
+          cb.call(pill)
+        rescue StandardError => e
+          Wurk.configuration.handle_exception(e, context: 'Wurk::Middleware::PoisonPill')
+        end
+      end
+    end
+  end
+end

data/lib/wurk/middleware.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Sidekiq-compatible middleware contract. Both client and server middleware
+  # share the same surface (Sidekiq aliases `ClientMiddleware = ServerMiddleware`).
+  # Including this gives a middleware class a `config` setter (the Chain assigns
+  # it via `Entry#make_new`) plus convenience accessors to the bound config's
+  # Redis pool and logger.
+  #
+  # `config` is either a Wurk::Configuration or a Wurk::Capsule — both expose
+  # `redis_pool`, `redis`, `logger`. Treat config as the single seam between
+  # middleware and the host process.
+  #
+  # Spec: docs/target/sidekiq-free.md §10.2.
+  module Middleware
+    module ServerMiddleware
+      attr_accessor :config
+
+      def redis_pool
+        config.redis_pool
+      end
+
+      def logger
+        config.logger
+      end
+
+      def redis(&)
+        config.redis(&)
+      end
+    end
+
+    ClientMiddleware = ServerMiddleware
+  end
+end

data/lib/wurk/process_set.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Live process list view backed by the `processes` SET + per-identity hashes.
+  # Cluster topology lives here: dashboard process list, total concurrency
+  # gauge, RSS roll-up, leader lookup.
+  #
+  # Wire-compat is sacred — every Redis call matches Sidekiq OSS exactly.
+  # Spec: docs/target/sidekiq-free.md §1 (Redis schema), §19.6.
+  class ProcessSet
+    include Enumerable
+
+    # Order matters — index-aligned with the HMGET row.
+    BEAT_FIELDS = %w[busy beat quiet rss rtt_us].freeze
+    EACH_FIELDS = (%w[info concurrency] + BEAT_FIELDS).freeze
+    LOOKUP_FIELDS = (%w[info] + BEAT_FIELDS).freeze
+    private_constant :BEAT_FIELDS, :EACH_FIELDS, :LOOKUP_FIELDS
+
+    # `processes` SET only stores identity strings; the live hash at each
+    # identity expires every 60s, so SCARD can lag reality. Constructor
+    # opts into a `cleanup` (rate-limited globally to 1/min) so the size
+    # reported below reflects the post-prune state — except when caller
+    # explicitly skips it (e.g. inside `cleanup` itself, or for snapshot
+    # reads on hot paths).
+    #
+    # Positional Boolean matches Sidekiq's public API — wire-compat sacred.
+    def initialize(clean_plz = true) # rubocop:disable Style/OptionalBooleanParameter
+      cleanup if clean_plz
+    end
+
+    # Fetch a single Process by identity. Pipelined SISMEMBER + HMGET so
+    # absence (process never registered) and expiry (heartbeat lapsed,
+    # info field gone) both return nil.
+    def self.[](identity)
+      exists, fields = Wurk.redis do |conn|
+        conn.pipelined do |pipe|
+          pipe.call('SISMEMBER', Keys::PROCESSES, identity)
+          pipe.call('HMGET', identity, *LOOKUP_FIELDS)
+        end
+      end
+      return nil if exists.to_i.zero? || fields.first.nil?
+
+      build_process(LOOKUP_FIELDS.zip(fields).to_h)
+    end
+
+    # SREM identities whose `info` HASH field has expired. Rate-limited
+    # globally to 1/min via SET NX EX so concurrent dashboards / API calls
+    # don't dogpile the prune. Returns the number of identities removed
+    # (or 0 when the lock was held by someone else).
+    #
+    # Spec: docs/target/sidekiq-free.md §31.17.
+    def cleanup
+      return 0 unless acquired_cleanup_lock?
+
+      Wurk.redis do |conn|
+        procs = conn.call('SMEMBERS', Keys::PROCESSES)
+        next 0 if procs.empty?
+
+        heartbeats = conn.pipelined do |pipe|
+          procs.each { |key| pipe.call('HGET', key, 'info') }
+        end
+        to_prune = procs.zip(heartbeats).filter_map { |id, info| id if info.nil? }
+        next 0 if to_prune.empty?
+
+        conn.call('SREM', Keys::PROCESSES, *to_prune).to_i
+      end
+    end
+
+    # Pipelined identity → HMGET. Skips identities whose `info` field is
+    # gone (heartbeat expired between SMEMBERS and HMGET). Sorted by
+    # identity so iteration order is stable for dashboards.
+    def each
+      return enum_for(:each) unless block_given?
+
+      rows = fetch_each_rows
+      rows.each do |row|
+        attrs = EACH_FIELDS.zip(row).to_h
+        next if attrs['info'].nil?
+
+        yield ProcessSet.send(:build_process, attrs)
+      end
+    end
+
+    # SCARD over `processes`. Not pruned — may include identities whose
+    # heartbeat has lapsed. Use `each` for the accurate count.
+    def size
+      Wurk.redis { |conn| conn.call('SCARD', Keys::PROCESSES) }
+    end
+
+    # Sum of `concurrency` across live processes. Iterates `each` so dead
+    # identities are skipped.
+    def total_concurrency
+      sum { |p| p['concurrency'].to_i }
+    end
+
+    # Sum of `rss` (KB) across live processes.
+    def total_rss_in_kb
+      sum { |p| p['rss'].to_i }
+    end
+    alias total_rss total_rss_in_kb
+
+    # Cluster leader identity. Ent-only feature; OSS only reads the key.
+    # Memoized per-instance: dashboards re-instantiate ProcessSet per render.
+    # `||=` with empty-string fallback distinguishes "leader is unset" from
+    # "memoization not yet computed".
+    def leader
+      @leader ||= Wurk.redis { |c| c.call('GET', 'dear-leader') } || ''
+    end
+
+    class << self
+      private
+
+      # Builds a Wurk::Process from `{field_name => raw_value}`. Handles
+      # both the 6-field `[]` shape and the 7-field `each` shape — extra
+      # `concurrency` from the heartbeat overrides whatever `info` JSON
+      # claimed (heartbeat is fresher).
+      def build_process(attrs)
+        hash = Wurk.load_json(attrs.fetch('info')).merge(beat_overrides(attrs))
+        hash['concurrency'] = attrs['concurrency'].to_i if attrs.key?('concurrency')
+        Process.new(hash)
+      end
+
+      def beat_overrides(attrs)
+        {
+          'busy' => attrs['busy'].to_i,
+          'beat' => attrs['beat'].to_f,
+          'quiet' => attrs['quiet'],
+          'rss' => attrs['rss'].to_i,
+          'rtt_us' => attrs['rtt_us'].to_i
+        }
+      end
+    end
+
+    private
+
+    def fetch_each_rows
+      Wurk.redis do |conn|
+        procs = conn.call('SMEMBERS', Keys::PROCESSES).sort
+        next [] if procs.empty?
+
+        conn.pipelined do |pipe|
+          procs.each { |key| pipe.call('HMGET', key, *EACH_FIELDS) }
+        end
+      end
+    end
+
+    def acquired_cleanup_lock?
+      Wurk.redis { |conn| conn.call('SET', 'process_cleanup', '1', 'NX', 'EX', '60') } == 'OK'
+    end
+  end
+
+  # One row in the process list. `attribs` is the merged `info` JSON +
+  # per-beat fields (busy, beat, quiet, rss, rtt_us). All fields are
+  # read-only — mutations happen via signals (`<id>-signals` LIST), not
+  # by editing this hash.
+  #
+  # Spec: docs/target/sidekiq-free.md §19.6.
+  class Process
+    def initialize(hash)
+      @attribs = hash
+    end
+
+    def tag      = self['tag']
+    def labels   = self['labels'].to_a
+    def [](key)  = @attribs[key]
+    def identity = self['identity']
+    alias id identity
+
+    # Back-compat for dashboards predating capsules (pre-v8.0.8). New
+    # heartbeats write `capsules`; fall through to the legacy `queues`
+    # field if the process hasn't been upgraded yet.
+    def queues
+      if self['capsules']
+        capsules.values.flat_map { |c| c['weights'].keys }.uniq
+      else
+        self['queues']
+      end
+    end
+
+    # Back-compat sibling of `queues`. Two capsules processing the same
+    # queue name will collapse to a single weight — there's no useful way
+    # to merge them and the dashboard never displayed both.
+    def weights
+      return self['weights'] unless self['capsules']
+
+      capsules.values.each_with_object({}) do |cap, acc|
+        cap['weights'].each { |q, w| acc[q] = w }
+      end
+    end
+
+    def capsules  = self['capsules']
+    def version   = self['version']
+    def embedded? = self['embedded']
+
+    # SIGTSTP — drop fetch, drain in-flight. Asynchronous; takes one
+    # heartbeat (≤10s) for the target process to notice.
+    def quiet!
+      raise 'Cannot quiet an embedded process' if embedded?
+
+      signal('TSTP')
+    end
+
+    # SIGTERM — graceful shutdown within `shutdown_timeout`. Asynchronous.
+    def stop!
+      raise 'Cannot stop an embedded process' if embedded?
+
+      signal('TERM')
+    end
+
+    # SIGTTIN — dump every thread's backtrace. For diagnosing frozen
+    # processes that are still beating.
+    def dump_threads
+      signal('TTIN')
+    end
+
+    # Truthy when this process has accepted a TSTP and won't fetch new
+    # jobs. The heartbeat writes `quiet = "true"` after handling the
+    # signal — read-only here.
+    def stopping?
+      self['quiet'] == 'true'
+    end
+
+    # Compares identity against the `dear-leader` STRING. Ent-only;
+    # always false in OSS/free.
+    def leader?
+      Wurk.redis { |c| c.call('GET', 'dear-leader') == identity }
+    end
+
+    private
+
+    # LPUSH to `<identity>-signals` + EXPIRE 60s. Pipelined so a crashed
+    # caller can't leave a stray key behind without a TTL.
+    def signal(sig)
+      key = "#{identity}-signals"
+      Wurk.redis do |c|
+        c.pipelined do |pipe|
+          pipe.call('LPUSH', key, sig)
+          pipe.call('EXPIRE', key, 60)
+        end
+      end
+    end
+  end
+end