wurk 0.0.1

data/lib/wurk/heartbeat.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative 'component'
+require_relative 'keys'
+require_relative 'processor'
+
+module Wurk
+  # Single-purpose owner of the Redis-side process heartbeat. Lifted out of
+  # Wurk::Launcher so the launcher can stay focused on lifecycle and so the
+  # heartbeat schema lives in one place readers can grep for.
+  #
+  # Each beat is one pipelined round-trip:
+  #   SADD   processes <identity>
+  #   HSET   <identity>          info concurrency busy beat quiet rss rtt_us
+  #   EXPIRE <identity>          60
+  #   UNLINK <identity>:work
+  #   HSET   <identity>:work     <tid> <json> ...    (only if WORK_STATE non-empty)
+  #   EXPIRE <identity>:work     60                  (only if WORK_STATE non-empty)
+  #   LPOP   <identity>-signals  × BEAT_PAUSE
+  #
+  # The work hash is UNLINK-then-rewritten on every beat — a dropped beat
+  # momentarily empties it, and ProcessSet#cleanup compensates by SREM-ing
+  # identities whose `info` field has expired.
+  #
+  # Heartbeat owns only the wire. Signals queued by the dashboard are pulled
+  # out of the pipelined results and returned to the caller for dispatch —
+  # TSTP/TERM semantics live in Launcher.
+  #
+  # `:heartbeat` fires once on the first successful beat and again after any
+  # network partition (rearmed when beat! rescues). `:beat` fires every tick.
+  #
+  # Spec: docs/target/sidekiq-free.md §12 (Launcher#❤️).
+  class Heartbeat
+    include Component
+
+    # Cadence in seconds. Key TTL is 60s — a process is dead after ~6 misses.
+    BEAT_PAUSE = 10
+    TTL_SECONDS = 60
+
+    attr_reader :identity, :rtt_us, :last_beat_at
+
+    # `quiet:` is a callable so Launcher can keep ownership of its `@done`
+    # flag without an awkward setter contract. `info_overrides:` lets the
+    # caller (Launcher#embedded, tests) inject fields without forcing
+    # Heartbeat to know about every flag the host process tracks.
+    def initialize(identity:, config:, started_at: nil, embedded: false, quiet: nil)
+      @identity = identity
+      @config = config
+      @started_at = started_at || Time.now.to_f
+      @embedded = embedded
+      @quiet_proc = quiet || -> { false }
+      @first_heartbeat = true
+      @rtt_us = 0
+    end
+
+    # Pipelined beat. Returns the drained signals as Array<String> on
+    # success, or nil if Redis raised — the next successful beat refires
+    # `:heartbeat` so partition recovery is observable.
+    def beat!
+      sigs, @rtt_us = pipelined_beat
+      @last_beat_at = Time.now.to_f
+      if @first_heartbeat
+        @first_heartbeat = false
+        fire_event(:heartbeat)
+      end
+      fire_event(:beat, oneshot: false)
+      emit_statsd_gauges
+      sigs.compact
+    rescue StandardError => e
+      @first_heartbeat = true
+      handle_exception(e, { context: 'heartbeat' })
+      nil
+    end
+
+    # Best-effort teardown. SREM removes us from the live list; UNLINK
+    # drops the identity hash and its work mirror. Idempotent: if Redis
+    # is down the next process boot's ProcessSet#cleanup prunes us.
+    def stop!
+      redis do |conn|
+        conn.pipelined do |pipe|
+          pipe.call('SREM', Keys::PROCESSES, @identity)
+          pipe.call('UNLINK', @identity, "#{@identity}:work")
+        end
+      end
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    # Two extra writes (HSET + EXPIRE for the work mirror) when WORK_STATE
+    # has entries, so `lead` shifts to skip them when slicing signals out
+    # of the pipeline result.
+    def pipelined_beat
+      work_snapshot = Processor::WORK_STATE.dup
+      lead = 4 + (work_snapshot.empty? ? 0 : 2)
+      t0 = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
+      results = redis { |conn| conn.pipelined { |pipe| write_beat(pipe, work_snapshot) } }
+      rtt = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond) - t0
+      [results[lead, BEAT_PAUSE] || [], rtt]
+    end
+
+    def write_beat(pipe, work_snapshot)
+      pipe.call('SADD', Keys::PROCESSES, @identity)
+      pipe.call('HSET', @identity, *beat_hash_args(work_snapshot.size))
+      pipe.call('EXPIRE', @identity, TTL_SECONDS)
+      write_work_hash(pipe, work_snapshot)
+      drain_signals(pipe)
+    end
+
+    def beat_hash_args(busy)
+      [
+        'info', Wurk.dump_json(info_hash),
+        'concurrency', total_concurrency.to_s,
+        'busy', busy.to_s,
+        'beat', Time.now.to_f.to_s,
+        'quiet', @quiet_proc.call.to_s,
+        'rss', memory_usage_kb.to_s,
+        'rtt_us', @rtt_us.to_s
+      ]
+    end
+
+    def write_work_hash(pipe, work_snapshot)
+      work_key = "#{@identity}:work"
+      pipe.call('UNLINK', work_key)
+      return if work_snapshot.empty?
+
+      args = work_snapshot.flat_map { |tid, hash| [tid.to_s, Wurk.dump_json(hash)] }
+      pipe.call('HSET', work_key, *args)
+      pipe.call('EXPIRE', work_key, TTL_SECONDS)
+    end
+
+    # LPOP one entry per second of cadence so a flood of queued signals
+    # can't stall the beat; anything older drains on the next beat.
+    def drain_signals(pipe)
+      BEAT_PAUSE.times { pipe.call('LPOP', "#{@identity}-signals") }
+    end
+
+    def info_hash
+      caps = @config.capsules.each_value
+      {
+        'hostname' => hostname,
+        'started_at' => @started_at,
+        'pid' => ::Process.pid,
+        'tag' => @config[:tag] || default_tag,
+        'concurrency' => total_concurrency,
+        'capsules' => capsules_info,
+        'queues' => caps.flat_map(&:queues).uniq,
+        'weights' => caps.map(&:weights),
+        'labels' => Array(@config[:labels]),
+        'identity' => @identity,
+        'version' => Wurk::VERSION,
+        'embedded' => @embedded
+      }
+    end
+
+    def capsules_info
+      @config.capsules.transform_values do |cap|
+        { 'concurrency' => cap.concurrency, 'mode' => cap.mode.to_s, 'weights' => cap.weights }
+      end
+    end
+
+    def total_concurrency
+      @config.capsules.each_value.sum(&:concurrency)
+    end
+
+    # Best-effort statsd snapshot per beat. Emits `sidekiq.busy` (this
+    # process's in-flight job count) and `sidekiq.queue.size` (per queue
+    # LLEN). Tagged with `process:<identity>` so multi-process emissions
+    # of the global `queue.size` are tag-distinguishable downstream — pick
+    # `max` across the process tag in your dashboard. No-op when
+    # `config.dogstatsd` is unset (Statsd.gauge short-circuits on nil
+    # client) so the LLEN pipeline is also skipped.
+    # Spec hint: docs/target/sidekiq-ent.md §5.2 names (`busy`, `queue.size`).
+    def emit_statsd_gauges
+      return unless Wurk::Metrics::Statsd.client
+
+      busy = Processor::WORK_STATE.size
+      Wurk::Metrics::Statsd.gauge('busy', busy, tags: ["process:#{@identity}"])
+      emit_queue_sizes
+    rescue StandardError => e
+      handle_exception(e, { context: 'heartbeat metrics' })
+    end
+
+    def emit_queue_sizes
+      queues = @config.capsules.each_value.flat_map(&:queues).uniq
+      return if queues.empty?
+
+      sizes = redis { |conn| conn.pipelined { |pipe| queues.each { |q| pipe.call('LLEN', "queue:#{q}") } } }
+      queues.zip(sizes).each do |queue, size|
+        Wurk::Metrics::Statsd.gauge(
+          'queue.size', size,
+          tags: ["queue:#{queue}", "process:#{@identity}"]
+        )
+      end
+    end
+
+    # Linux first via /proc/self/statm[1] (resident pages × 4 KB);
+    # `ps` fallback for macOS/BSD test runners. Zero on failure — the
+    # dashboard shows "—" rather than crashing.
+    def memory_usage_kb
+      if ::File.exist?('/proc/self/statm')
+        ::File.read('/proc/self/statm').split[1].to_i * 4
+      else
+        `ps -o rss= -p #{::Process.pid}`.to_i
+      end
+    rescue StandardError
+      0
+    end
+  end
+end

data/lib/wurk/iterable_job.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'job'
+
+module Wurk
+  # Iterable jobs split long-running work into small, idempotent chunks.
+  # Override `#build_enumerator` (yielding `[item, new_cursor]` pairs) and
+  # `#each_iteration(item, *args)`; the framework drives the loop, persists
+  # the cursor, and resumes after interruption.
+  #
+  # Defining `#perform` on the including class is refused at `method_added`
+  # — IterableJob owns the run loop. User code overrides `#each_iteration`.
+  #
+  # State lives in the `it-<jid>` HASH (sidekiq-free.md §1.5):
+  #
+  #   ex        : execution count (int)
+  #   c         : cursor (JSON string)
+  #   rt        : runtime accumulated (float seconds)
+  #   cancelled : timestamp (int) if cancelled
+  #
+  # Spec: docs/target/sidekiq-free.md §6.4.
+  module IterableJob # rubocop:disable Metrics/ModuleLength
+    # Alias to the canonical `Wurk::Job::Interrupted`. The exception lives on
+    # `Wurk::Job` so non-iterable code paths (manual `interrupted?` checks)
+    # can raise the same class; the interrupt-handler middleware rescues by
+    # the `Wurk::Job::Interrupted` name.
+    Interrupted = Wurk::Job::Interrupted
+
+    # Default expiry for an iteration state HASH while the job is running or
+    # awaiting resume. Refreshed on every checkpoint.
+    STATE_TTL = 30 * 86_400
+
+    # Cursor flush + cancellation poll cadence. Both share the timer so
+    # a long-running iteration that hits the 5-second mark checkpoints
+    # *and* checks for cross-process cancellation in the same tick.
+    STATE_FLUSH_INTERVAL = 5
+
+    # Shorter TTL applied once the state is marked cancelled. The HASH
+    # outlives `cancel!` long enough for live workers to observe the flag
+    # but is reaped well before the 30-day default would expire.
+    CANCELLATION_PERIOD = 3 * 86_400
+
+    # Class-level guard injected via singleton-class prepend so we can call
+    # `super` cleanly and stay compatible with anything else hooking
+    # `method_added`.
+    module MethodAddedGuard
+      def method_added(method_name)
+        if method_name == :perform
+          raise ArgumentError,
+                "#{self} is an IterableJob; override #each_iteration instead of #perform"
+        end
+        super
+      end
+    end
+
+    def self.included(base)
+      base.include(Wurk::Job)
+      base.singleton_class.prepend(MethodAddedGuard)
+    end
+
+    # User overrides — must return an Enumerator yielding `[item, new_cursor]`
+    # pairs. The cursor must round-trip through JSON.
+    def build_enumerator(*, cursor:)
+      _ = cursor
+      raise NotImplementedError, "#{self.class} must override #build_enumerator"
+    end
+
+    def each_iteration(*)
+      raise NotImplementedError, "#{self.class} must override #each_iteration"
+    end
+
+    # --- lifecycle hooks (no-op defaults; users override as needed) -----
+
+    def on_start; end
+    def on_resume; end
+    def on_stop; end
+    def on_cancel; end
+    def on_complete; end
+
+    def around_iteration
+      yield
+    end
+
+    # --- iteration state accessors --------------------------------------
+
+    attr_reader :current_object
+
+    def arguments
+      @arguments ||= []
+    end
+
+    def cursor
+      @cursor
+    end
+
+    # Mark this iteration cancelled. Sets the in-process flag immediately
+    # (so the next `cancelled?` check inside the run loop trips) and, when
+    # a jid is bound, writes the timestamp to the `it-<jid>` HASH so other
+    # processes observe it on their next 5-second poll.
+    #
+    # Returns the integer epoch-seconds timestamp written.
+    def cancel!
+      ts_ms = ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+      @cancelled_at ||= ts_ms
+      ts = ts_ms / 1000
+      persist_cancellation(ts)
+      ts
+    end
+
+    # True once `cancel!` has been called locally, OR — for cross-process
+    # cancellation — once the `cancelled` field appears in the `it-<jid>`
+    # HASH. The remote check is rate-limited to once per `STATE_FLUSH_INTERVAL`
+    # to keep the hot loop cheap.
+    def cancelled?
+      return true if @cancelled_at
+
+      ts = poll_remote_cancellation
+      return false unless ts
+
+      @cancelled_at = ts * 1000
+      true
+    end
+
+    # Redis HASH key holding iteration state for this job. Wire-compat
+    # with Sidekiq's `it-<jid>` schema (sidekiq-free.md §1.5).
+    def iteration_key
+      "it-#{jid}"
+    end
+
+    # Foundation run loop. Loads any persisted state, drives the enumerator,
+    # checkpoints every `STATE_FLUSH_INTERVAL`, and on interruption persists
+    # the final cursor before re-raising so the interrupt-handler middleware
+    # can re-push the job at the head of the queue.
+    def perform(*args)
+      reset_run_state(args)
+      load_state
+      fire_lifecycle_start
+      @executions += 1
+
+      run_iterations(args)
+
+      finalize_complete
+    rescue Interrupted
+      finalize_interrupted
+      raise
+    end
+
+    private
+
+    def reset_run_state(args)
+      @cancelled_at = nil
+      @arguments = args
+      @last_cancel_poll_ms = nil
+      @last_flush_ms = nil
+      @run_started_at = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      @executions = 0
+      @runtime_acc = 0.0
+      @cursor = nil
+    end
+
+    def fire_lifecycle_start
+      if @executions.positive?
+        on_resume
+      else
+        on_start
+      end
+    end
+
+    def run_iterations(args)
+      enum = build_enumerator(*args, cursor: @cursor)
+      enum.each do |item, new_cursor|
+        raise Interrupted if cancelled?
+
+        @current_object = item
+        around_iteration { each_iteration(item, *args) }
+        @cursor = new_cursor
+        maybe_flush_state
+      end
+    end
+
+    def finalize_complete
+      flush_state(final: true)
+      on_complete
+      delete_state
+    end
+
+    def finalize_interrupted
+      flush_state(final: true)
+      on_cancel if @cancelled_at
+      on_stop
+    end
+
+    # --- persistence ----------------------------------------------------
+
+    def load_state
+      return unless persistable?
+
+      hash = normalize_hgetall(redis_call('HGETALL', iteration_key))
+      return if hash.empty?
+
+      apply_loaded_state(hash)
+    end
+
+    def apply_loaded_state(hash)
+      @executions   = hash['ex'].to_i               if hash['ex']
+      @runtime_acc  = hash['rt'].to_f               if hash['rt']
+      @cursor       = ::JSON.parse(hash['c'])       if hash['c']
+      @cancelled_at = hash['cancelled'].to_i * 1000 if hash['cancelled']
+    end
+
+    def maybe_flush_state
+      return unless persistable?
+
+      now_ms = ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+      @last_flush_ms ||= now_ms
+      return if now_ms - @last_flush_ms < STATE_FLUSH_INTERVAL * 1000
+
+      flush_state
+      @last_flush_ms = now_ms
+    end
+
+    def flush_state(final: false)
+      return unless persistable?
+
+      runtime = @runtime_acc + (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - @run_started_at)
+      @runtime_acc = runtime if final
+      ttl = @cancelled_at ? CANCELLATION_PERIOD : STATE_TTL
+      redis_pool.with do |conn|
+        conn.pipelined do |pipe|
+          pipe.call('HSET', iteration_key,
+                    'ex', @executions.to_s,
+                    'c',  ::JSON.generate(@cursor),
+                    'rt', runtime.to_s)
+          pipe.call('EXPIRE', iteration_key, ttl)
+        end
+      end
+    end
+
+    def delete_state
+      return unless persistable?
+
+      redis_call('DEL', iteration_key)
+    end
+
+    def persist_cancellation(timestamp)
+      return unless persistable?
+
+      redis_pool.with do |conn|
+        conn.pipelined do |pipe|
+          pipe.call('HSET', iteration_key, 'cancelled', timestamp)
+          pipe.call('EXPIRE', iteration_key, CANCELLATION_PERIOD)
+        end
+      end
+    end
+
+    def poll_remote_cancellation
+      return nil unless persistable?
+
+      now_ms = ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+      return nil if @last_cancel_poll_ms && now_ms - @last_cancel_poll_ms < STATE_FLUSH_INTERVAL * 1000
+
+      @last_cancel_poll_ms = now_ms
+      raw = redis_call('HGET', iteration_key, 'cancelled')
+      raw && !raw.to_s.empty? ? raw.to_i : nil
+    end
+
+    # --- helpers --------------------------------------------------------
+
+    def persistable?
+      !jid.nil? && !jid.to_s.empty?
+    end
+
+    def redis_pool
+      Wurk.redis_pool
+    end
+
+    def redis_call(*args)
+      redis_pool.with { |conn| conn.call(*args) }
+    end
+
+    # redis-client returns HGETALL as a flat array on some adapters and as
+    # a Hash on others. Normalize to a Hash with String keys/values either way.
+    def normalize_hgetall(raw)
+      case raw
+      when Hash  then raw
+      when Array then raw.each_slice(2).to_h
+      else            {}
+      end
+    end
+  end
+end

data/lib/wurk/job/options.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Wurk
+  module Job
+    # Options-only slice of the Wurk::Worker DSL. Mixed into `ActiveJob::Base`
+    # by the wurk adapter so native AJ classes can configure Wurk/Sidekiq
+    # features (`sidekiq_options retry: 3`, `sidekiq_retry_in { ... }`, …)
+    # without including the full `perform_async`/`set` surface that doesn't
+    # apply to AJ.
+    #
+    # Aliased as `Sidekiq::Job::Options`. Wire-compat sacred — third-party
+    # gems that extend AJ via this module load unchanged.
+    #
+    # Spec: docs/target/sidekiq-free.md §6 (Sidekiq::Job::Options).
+    module Options
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def sidekiq_options(opts = {})
+          merged = get_sidekiq_options.merge(opts.transform_keys(&:to_s))
+          @sidekiq_options_hash = merged
+        end
+
+        # Sidekiq's public API name — must stay `get_sidekiq_options`.
+        def get_sidekiq_options # rubocop:disable Naming/AccessorMethodName
+          @sidekiq_options_hash ||= inherited_sidekiq_options # rubocop:disable Naming/MemoizedInstanceVariableName
+        end
+
+        def sidekiq_options_hash
+          get_sidekiq_options
+        end
+
+        attr_reader :sidekiq_retry_in_block, :sidekiq_retries_exhausted_block
+
+        def sidekiq_retry_in(&block)
+          @sidekiq_retry_in_block = block
+        end
+
+        def sidekiq_retries_exhausted(&block)
+          @sidekiq_retries_exhausted_block = block
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@sidekiq_options_hash, get_sidekiq_options.dup)
+          inherit_ivar(subclass, :@sidekiq_retry_in_block)
+          inherit_ivar(subclass, :@sidekiq_retries_exhausted_block)
+        end
+
+        private
+
+        def inherited_sidekiq_options
+          if superclass.respond_to?(:get_sidekiq_options)
+            superclass.get_sidekiq_options.dup
+          else
+            Wurk.default_job_options.dup
+          end
+        end
+
+        def inherit_ivar(subclass, ivar)
+          return unless instance_variable_defined?(ivar)
+
+          subclass.instance_variable_set(ivar, instance_variable_get(ivar))
+        end
+      end
+    end
+  end
+end

data/lib/wurk/job.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'worker'
+
+module Wurk
+  # Sidekiq 7+ alias for Wurk::Worker. `include Wurk::Job` and
+  # `include Sidekiq::Job` are the same surface.
+  #
+  # Instance-level `jid`, `_context`, `interrupted?`, and `logger` come
+  # from Wurk::Worker. Class-level DSL (`sidekiq_options`, `perform_*`,
+  # `set`, retry blocks) does too — Job is a pure alias module that
+  # re-exposes Worker under the modern name.
+  module Job
+    # Raised mid-iteration when the run loop must yield — either a swarm
+    # shutdown signal or a cooperative cancellation. The interrupt-handler
+    # middleware catches it, re-pushes the job, and raises
+    # `Wurk::JobRetry::Skip` so the retry layer skips error bookkeeping.
+    # User code must not rescue this.
+    #
+    # Spec: docs/target/sidekiq-free.md §6.4.
+    class Interrupted < RuntimeError; end
+
+    def self.included(base)
+      base.include(Wurk::Worker)
+    end
+
+    # Mirror the module-level test helpers so `Sidekiq::Job.jobs /
+    # clear_all / drain_all` work the same as `Sidekiq::Worker.*`.
+    def self.jobs       = Wurk::Worker.jobs
+    def self.clear_all  = Wurk::Worker.clear_all
+    def self.drain_all  = Wurk::Worker.drain_all
+  end
+end

data/lib/wurk/job_logger.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Wraps the per-job execution span. Logs "start"/"done"/"fail" at INFO,
+  # pushes :elapsed into Wurk::Context so the logger formatter can pick it
+  # up, and prepares the thread-local context hash (jid, class, plus
+  # config[:logged_job_attributes]).
+  #
+  # Two entry points, called from Processor#process in this order:
+  #   1. prepare(job_hash) { ... }  → sets thread-local context, applies
+  #      per-job log_level, yields to the rest of dispatch.
+  #   2. call(item, queue) { ... }  → wraps the actual perform with the
+  #      start/done/fail log line trio and the elapsed-ms measurement.
+  #
+  # Skipping default logging is controlled by config[:skip_default_job_logging];
+  # the prepare step still runs so context/log_level still apply.
+  #
+  # Spec: docs/target/sidekiq-free.md §18.
+  class JobLogger
+    def initialize(config)
+      @config = config
+      @logger = @config.logger
+      @skip = !!@config[:skip_default_job_logging]
+    end
+
+    def call(_item, _queue)
+      start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      @logger.info { 'start' } unless @skip
+
+      yield
+
+      Wurk::Context.add(:elapsed, elapsed(start))
+      @logger.info { 'done' } unless @skip
+    rescue Exception # rubocop:disable Lint/RescueException
+      Wurk::Context.add(:elapsed, elapsed(start))
+      @logger.info { 'fail' } unless @skip
+      raise
+    end
+
+    # Sets thread-local context for the duration of `block`, optionally
+    # under a per-job log level. ActiveJob-wrapped jobs expose the real
+    # class via the "wrapped" key — log that, not the wrapper.
+    def prepare(job_hash, &block)
+      h = {
+        jid: job_hash['jid'],
+        class: job_hash['wrapped'] || job_hash['class']
+      }
+      @config[:logged_job_attributes].each do |attr|
+        h[attr.to_sym] = job_hash[attr] if job_hash.key?(attr)
+      end
+
+      level = job_hash['log_level']
+      Wurk::Context.with(h) do
+        if level
+          @logger.with_level(level, &block)
+        else
+          yield
+        end
+      end
+    end
+
+    private
+
+    def elapsed(start)
+      (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start).round(3)
+    end
+  end
+end