wurk 0.0.1

data/lib/wurk/worker.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative 'worker/setter'
+
+module Wurk
+  # The user-facing DSL: `include Wurk::Worker` (aliased to Sidekiq::Worker).
+  # Owns `sidekiq_options`, `perform_async`, `perform_in`, `perform_at`,
+  # `set`, `sidekiq_retry_in`, etc.
+  #
+  # Spec: docs/target/sidekiq-free.md §6 (Sidekiq::Job).
+  module Worker
+    # Interval values below this threshold are interpreted as seconds-from-now;
+    # values at or above are treated as absolute epoch timestamps.
+    # Threshold matches Sidekiq exactly — wire-compat sacred.
+    SCHEDULED_THRESHOLD = 1_000_000_000
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.module_eval { attr_accessor :jid, :_context }
+      base.singleton_class.module_eval do
+        attr_accessor :sidekiq_retry_in_block, :sidekiq_retries_exhausted_block
+      end
+    end
+
+    # Module-level test helpers: `Sidekiq::Worker.jobs / clear_all / drain_all`
+    # operate across every job class (spec §24.3). Resolved lazily so the
+    # testing constants need not be loaded when Worker is.
+    def self.jobs       = ::Wurk::Queues.jobs
+    def self.clear_all  = ::Wurk::Queues.clear_all
+    def self.drain_all  = ::Wurk::Testing.drain_all
+
+    def logger
+      Wurk.logger
+    end
+
+    # Cooperative cancellation flag for IterableJob and long-running jobs.
+    # Returns false when no processor context has been attached.
+    def interrupted?
+      ctx = @_context
+      ctx.respond_to?(:stopping?) && ctx.stopping?
+    end
+
+    # Batch helpers (Pro). Available on every worker — return nil when the
+    # current job did not originate from a batch.
+    #
+    # Spec: docs/target/sidekiq-pro.md §2.6.
+    def bid
+      @bid
+    end
+
+    # @api private — Processor sets this from job_hash['bid'] before perform.
+    attr_writer :bid
+
+    def batch
+      return nil if @bid.nil?
+
+      Wurk::Batch.new(@bid)
+    end
+
+    # False if the batch was invalidated. Workers should `return unless
+    # valid_within_batch?` to short-circuit work for cancelled batches.
+    def valid_within_batch?
+      return true if @bid.nil?
+
+      batch.valid?
+    end
+
+    module ClassMethods # rubocop:disable Metrics/ModuleLength
+      def sidekiq_options(opts = {})
+        merged = get_sidekiq_options.merge(opts.transform_keys(&:to_s))
+        @sidekiq_options_hash = merged
+      end
+
+      # Sidekiq's public API name — wire-compat sacred. 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
+
+      def queue_as(queue)
+        sidekiq_options('queue' => queue.to_s)
+      end
+
+      def sidekiq_retry_in(&block)
+        self.sidekiq_retry_in_block = block
+      end
+
+      def sidekiq_retries_exhausted(&block)
+        self.sidekiq_retries_exhausted_block = block
+      end
+
+      def perform_async(*)
+        Wurk::Worker::Setter.new(self, {}).perform_async(*)
+      end
+
+      def perform_inline(*)
+        new.perform(*)
+      end
+      alias perform_sync perform_inline
+
+      def perform_in(interval, *)
+        Wurk::Worker::Setter.new(self, {}).perform_in(interval, *)
+      end
+      alias perform_at perform_in
+
+      def perform_bulk(items, **)
+        Wurk::Worker::Setter.new(self, {}).perform_bulk(items, **)
+      end
+
+      def set(opts)
+        Wurk::Worker::Setter.new(self, opts)
+      end
+
+      def client_push(item)
+        raise ArgumentError, "Job arguments to #{name || self} must have string keys" if symbol_keyed?(item)
+
+        build_client.push(item)
+      end
+
+      def build_client
+        pool = get_sidekiq_options['pool']
+        Wurk::Client.new(pool: pool)
+      end
+
+      # --- Sidekiq::Testing class-level helpers (spec §24.3) --------------
+      # Only meaningful in :fake / :inline mode; the in-memory store is empty
+      # otherwise.
+
+      def queue
+        get_sidekiq_options['queue']
+      end
+
+      # Fake jobs enqueued for this class, across every queue.
+      def jobs
+        ::Wurk::Queues.jobs_by_class[to_s] || []
+      end
+
+      def clear
+        ::Wurk::Queues.clear_class(to_s)
+      end
+
+      # Run & remove every fake job for this class — including ones it enqueues
+      # mid-drain. Returns the count processed.
+      def drain
+        count = 0
+        while (job = ::Wurk::Queues.shift_class(to_s))
+          process_job(job)
+          count += 1
+        end
+        count
+      end
+
+      # Run & remove the first fake job for this class; EmptyQueueError if none.
+      def perform_one
+        job = ::Wurk::Queues.shift_class(to_s)
+        raise ::Wurk::Testing::EmptyQueueError, "no #{self} jobs were found" if job.nil?
+
+        process_job(job)
+      end
+
+      # Execute a normalized job hash through the inline server-middleware chain
+      # (empty by default — see Wurk::Testing.server_middleware).
+      # Returns the value of the server-middleware `invoke` (i.e. the worker's
+      # `perform` return), matching Sidekiq::Testing — so `perform_one` yields
+      # the job result.
+      def process_job(job_hash)
+        instance = new
+        instance.jid = job_hash['jid']
+        instance.bid = job_hash['bid'] if instance.respond_to?(:bid=)
+        ::Wurk::Testing.server_middleware.invoke(instance, job_hash, job_hash['queue'] || queue) do
+          execute_job(instance, job_hash['args'])
+        end
+      end
+
+      def execute_job(worker, args)
+        worker.perform(*args)
+      end
+
+      def delay(*)
+        raise ArgumentError, "#{name || self}.delay is removed in Sidekiq 7+. Use #{name || 'klass'}.perform_async."
+      end
+      alias delay_for delay
+      alias delay_until delay
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@sidekiq_options_hash, get_sidekiq_options.dup)
+        inherit_block(subclass, :@sidekiq_retry_in_block)
+        inherit_block(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_block(subclass, ivar)
+        return unless instance_variable_defined?(ivar)
+
+        subclass.instance_variable_set(ivar, instance_variable_get(ivar))
+      end
+
+      def symbol_keyed?(item)
+        item.respond_to?(:keys) && item.keys.any?(Symbol)
+      end
+    end
+  end
+end

data/lib/wurk.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+# Standalone entry point. Loading "wurk" must work without Rails.
+# The engine and railtie live under "wurk/rails" and are only loaded
+# when the host app opts in.
+
+require_relative 'wurk/version'
+require_relative 'wurk/keys'
+require_relative 'wurk/redis_pool'
+require_relative 'wurk/middleware'
+require_relative 'wurk/middleware/chain'
+require_relative 'wurk/component'
+require_relative 'wurk/context'
+require_relative 'wurk/logger'
+require_relative 'wurk/job_logger'
+require_relative 'wurk/capsule'
+require_relative 'wurk/configuration'
+require_relative 'wurk/job_util'
+require_relative 'wurk/client'
+require_relative 'wurk/client/buffered'
+require_relative 'wurk/worker'
+require_relative 'wurk/worker/setter'
+require_relative 'wurk/job'
+require_relative 'wurk/job/options'
+require_relative 'wurk/queues'
+require_relative 'wurk/testing'
+require_relative 'wurk/iterable_job'
+require_relative 'wurk/job_retry'
+require_relative 'wurk/job_record'
+require_relative 'wurk/queue'
+require_relative 'wurk/sorted_entry'
+require_relative 'wurk/job_set'
+require_relative 'wurk/retry_set'
+require_relative 'wurk/scheduled_set'
+require_relative 'wurk/dead_set'
+require_relative 'wurk/stats'
+require_relative 'wurk/process_set'
+require_relative 'wurk/work_set'
+require_relative 'wurk/heartbeat'
+require_relative 'wurk/fetcher'
+require_relative 'wurk/fetcher/reliable'
+require_relative 'wurk/processor'
+require_relative 'wurk/manager'
+require_relative 'wurk/lua'
+require_relative 'wurk/scheduled'
+require_relative 'wurk/launcher'
+require_relative 'wurk/cli'
+require_relative 'wurk/embedded'
+require_relative 'wurk/swarm'
+require_relative 'wurk/topology'
+require_relative 'wurk/batch'
+require_relative 'wurk/batch/status'
+require_relative 'wurk/batch_set'
+require_relative 'wurk/limiter'
+require_relative 'wurk/cron'
+require_relative 'wurk/leader'
+require_relative 'wurk/unique'
+require_relative 'wurk/encryption'
+require_relative 'wurk/metrics'
+require_relative 'wurk/metrics/statsd'
+require_relative 'wurk/metrics/history'
+require_relative 'wurk/metrics/query'
+require_relative 'wurk/web'
+require_relative 'wurk/deploy'
+
+require 'json'
+
+module Wurk
+  class Error < StandardError; end
+
+  # Raised inside a worker process to abort the run loop. User code must not
+  # rescue this — the swarm uses it to signal teardown across thread boundaries.
+  # Spec: docs/target/sidekiq-free.md §3.
+  class Shutdown < Interrupt; end
+
+  # Process-wide job option defaults. Per-class options from `sidekiq_options`
+  # take precedence; this hash is the floor.
+  DEFAULT_JOB_OPTIONS = { 'retry' => true, 'queue' => 'default' }.freeze
+
+  class << self
+    def configure_server(&)
+      configuration.configure_server(&)
+    end
+
+    def configure_client(&)
+      configuration.configure_client(&)
+    end
+
+    # Embedded mode: caller runs Wurk inside its own process (Puma, rake task,
+    # etc.) without forking. Concurrency is defaulted to 2 — the GIL makes
+    # higher thread counts counterproductive inside a host process that has
+    # its own pool. The block can override anything before the Embedded
+    # instance is built. Returns a Wurk::Embedded the caller drives with
+    # `#run` / `#quiet` / `#stop`.
+    def configure_embed
+      if configuration.frozen?
+        raise FrozenError, 'Wurk configuration is frozen; build all embedded instances before calling run'
+      end
+
+      configuration.concurrency = 2
+      yield configuration if block_given?
+      Embedded.new(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias default_configuration configuration
+
+    def redis(&)
+      redis_pool.with(&)
+    end
+
+    # Capsule-aware pool lookup. Thread-local override wins so per-capsule
+    # workers (`Thread.current[:wurk_capsule] = cap`) read from their own
+    # connections without leaking to the default capsule.
+    def redis_pool
+      (Thread.current[:wurk_capsule] || configuration.default_capsule).redis_pool
+    end
+
+    def logger
+      configuration.logger
+    end
+
+    # --- JSON ---------------------------------------------------------
+
+    def load_json(string)
+      ::JSON.parse(string)
+    end
+
+    def dump_json(object)
+      ::JSON.generate(object)
+    end
+
+    # --- default job options -----------------------------------------
+
+    def default_job_options
+      @default_job_options ||= DEFAULT_JOB_OPTIONS.dup
+    end
+
+    # Merges (does not replace) into the current defaults. Keys are
+    # stringified so symbol-keyed callers don't shadow string keys.
+    def default_job_options=(hash)
+      @default_job_options = default_job_options.merge(hash.transform_keys(&:to_s))
+    end
+
+    # --- strict args -------------------------------------------------
+
+    # Sets the global mode used by Wurk::JobUtil#verify_json.
+    # mode ∈ [:raise, :warn, false].
+    def strict_args!(mode = :raise)
+      @strict_args_mode = mode
+    end
+
+    # `defined?` distinguishes "never set" from "set to false".
+    def strict_args_mode
+      defined?(@strict_args_mode) ? @strict_args_mode : Configuration::DEFAULTS[:on_complex_arguments]
+    end
+
+    # --- mode flags --------------------------------------------------
+
+    # Sidekiq-compatible test-mode entry point. Delegates to Wurk::Testing
+    # (the single source of truth for the mode): a block scopes the mode to the
+    # current thread; no block sets it globally. `Sidekiq.testing!` aliases here.
+    def testing!(mode = :fake, &) = Wurk::Testing.__set_test_mode(mode, &)
+
+    # True when in :fake or :inline mode (i.e. not pushing to real Redis).
+    def testing? = Wurk::Testing.enabled?
+
+    # True inside the swarm/manager process (set by exe/wurk / the railtie).
+    def server?
+      !!@server
+    end
+
+    attr_writer :server
+
+    # Wurk ships Pro+Ent features in the free gem; these flags exist solely
+    # for third-party gems that branch on Sidekiq.pro? / Sidekiq.ent?.
+    def pro?
+      false
+    end
+
+    def ent?
+      false
+    end
+  end
+end
+
+# Batch worker classes (Empty, CallbackJob) and middleware load AFTER the
+# Wurk module class << self block — they instantiate workers at load time
+# via `sidekiq_options`, which reads Wurk.default_job_options.
+require_relative 'wurk/batch/empty'
+require_relative 'wurk/batch/callback_job'
+require_relative 'wurk/batch/callbacks'
+require_relative 'wurk/batch/client_middleware'
+require_relative 'wurk/batch/server_middleware'
+require_relative 'wurk/batch/death_handler'
+
+# Expiry must register AFTER Batch::ServerMiddleware so it sits inside that
+# middleware's onion — a skipped (expired) job then unwinds back through
+# batch's `yield` and gets counted as a batch success on the way out.
+# Spec: docs/target/sidekiq-pro.md §7.
+require_relative 'wurk/middleware/expiry'
+
+# Health probe HTTP server — opt-in via `config.health_check(port:)`. Loaded
+# at top level so the constants resolve in Launcher#build_health_server even
+# in standalone (no-Rails) boot.
+require_relative 'wurk/health'
+
+# Poison-pill detection — orphan recovery counter + dead set on threshold.
+# Spec: docs/target/sidekiq-pro.md §3.2.
+require_relative 'wurk/middleware/poison_pill'
+
+# Limiter server middleware: catches OverLimit, reschedules onto the same
+# queue with `Time.now + backoff` until `overrated` hits the reschedule cap.
+# Registered AFTER Batch::ServerMiddleware so a rescheduled OverLimit
+# unwinds back through the batch onion without ack'ing success.
+# Spec: docs/target/sidekiq-ent.md §1.4.
+Wurk.configuration.server_middleware.add(Wurk::Limiter::ServerMiddleware)
+
+# Statsd metrics middleware: per-job count / success / failure / perform_dist
+# emissions. No-op when `config.dogstatsd` is unset (Statsd.client returns
+# nil and the middleware yields straight through), so auto-registering here
+# has zero overhead for users who don't wire up a client. Matches Sidekiq
+# Pro's behavior of installing the middleware as soon as the gem is loaded.
+# Spec: docs/target/sidekiq-pro.md §9.
+Wurk.configuration.server_middleware.add(Wurk::Metrics::Statsd)
+
+# Pro Fast API: Lua-backed Queue#delete_job / #delete_by_class plus
+# SortedSet#scan { |JobRecord| … }. Mixed in via include/prepend on the
+# existing data API classes so the surface is wire-compat with Sidekiq Pro.
+# Spec: docs/target/sidekiq-pro.md §11.
+require_relative 'wurk/api/fast'
+
+# Sidekiq aliases load last — every Wurk::* constant they reference must be
+# fully defined first. compat.rb only redefines names, it does not gate
+# behavior, so trailing the load order is safe.
+require_relative 'wurk/compat'