wurk 0.0.1

data/lib/wurk/compat.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# Sidekiq aliases. This is the drop-in contract — every public Wurk::*
+# class is exposed under its Sidekiq::* name. Never break.
+#
+# Spec: docs/target/sidekiq-{free,pro,ent}.md.
+
+module Sidekiq
+  # Version stamps mirror Sidekiq's OSS release Wurk targets for compat.
+  # Third-party gems version-gate on these; raise the MAJOR only when the
+  # upstream Sidekiq major bumps and Wurk has matching surface.
+  NAME    = 'Sidekiq'
+  LICENSE = 'See LICENSE'
+  VERSION = '8.1.5'
+  MAJOR   = 8
+
+  # Namespace sentinels for Pro/Ent feature subclasses (Sidekiq::Pro::Web,
+  # Sidekiq::Enterprise::Crypto, …). Defined so downstream code can nest
+  # classes under them — but `Sidekiq.pro?` / `Sidekiq.ent?` still return
+  # `false` per docs/target/sidekiq-free.md §32 (Wurk advertises as free OSS).
+  module Pro; end
+
+  # Sidekiq Enterprise feature surface (`unique!`, `Crypto`, `Unique.locked?`).
+  # Wurk ships these free; the namespace exists for drop-in compat.
+  # Implementations live under `Wurk::*`; this module just delegates.
+  module Enterprise
+    class << self
+      # Installs the Wurk::Unique client+server middleware pair globally.
+      # Spec: docs/target/sidekiq-ent.md §3.1.
+      def unique!
+        Wurk::Unique.enable!
+      end
+
+      def unique?
+        Wurk::Unique.enabled?
+      end
+    end
+
+    # Wurk::Unique introspection: `Sidekiq::Enterprise::Unique.locked?(...)`.
+    # Spec §3.6.
+    module Unique
+      def self.locked?(*)
+        Wurk::Unique.locked?(*)
+      end
+    end
+
+    # AES-256-GCM args encryption. `Sidekiq::Enterprise::Crypto.enable(...)`
+    # delegates to `Wurk::Encryption.enable`. Spec: docs/target/sidekiq-ent.md §4.
+    module Crypto
+      class << self
+        def enable(active_version:, &)
+          Wurk::Encryption.enable(active_version: active_version, &)
+        end
+
+        def enabled?
+          Wurk::Encryption.enabled?
+        end
+      end
+    end
+  end
+
+  BasicFetch       = Wurk::Fetcher::Reliable
+  Batch            = Wurk::Batch
+  BatchSet         = Wurk::BatchSet
+  Capsule          = Wurk::Capsule
+  CLI              = Wurk::CLI
+  Client           = Wurk::Client
+  Component        = Wurk::Component
+  Config           = Wurk::Configuration
+  Context          = Wurk::Context
+  Cron             = Wurk::Cron
+  Periodic         = Wurk::Cron
+  DeadSet          = Wurk::DeadSet
+  Deploy           = Wurk::Deploy
+  Embedded         = Wurk::Embedded
+  Encryption       = Wurk::Encryption
+  IterableJob      = Wurk::IterableJob
+  Job              = Wurk::Job
+  JobLogger        = Wurk::JobLogger
+  JobRecord        = Wurk::JobRecord
+  JobRetry         = Wurk::JobRetry
+  JobUtil          = Wurk::JobUtil
+  Keys             = Wurk::Keys
+  Launcher         = Wurk::Launcher
+  Limiter          = Wurk::Limiter
+  Logger           = Wurk::Logger
+  Manager          = Wurk::Manager
+  Metrics          = Wurk::Metrics
+  Middleware       = Wurk::Middleware
+  ServerMiddleware = Wurk::Middleware::ServerMiddleware
+  ClientMiddleware = Wurk::Middleware::ClientMiddleware
+  Process          = Wurk::Process
+  ProcessSet       = Wurk::ProcessSet
+  Processor        = Wurk::Processor
+  Queue            = Wurk::Queue
+  RetrySet         = Wurk::RetrySet
+  Scheduled        = Wurk::Scheduled
+  ScheduledSet     = Wurk::ScheduledSet
+  Shutdown         = Wurk::Shutdown
+  Stats            = Wurk::Stats
+  Testing          = Wurk::Testing
+  Queues           = Wurk::Queues
+  EmptyQueueError  = Wurk::Testing::EmptyQueueError
+  Web              = Wurk::Web
+  Work             = Wurk::Work
+  Worker           = Wurk::Worker
+  Workers          = Wurk::Workers
+  WorkSet          = Wurk::WorkSet
+
+  # Top-level Sidekiq.configure_server / configure_client / redis / logger
+  # delegate to Wurk's class methods. Third-party gems treat these as the
+  # canonical entry points.
+  class << self
+    def configure_server(&) = Wurk.configure_server(&)
+    def configure_client(&) = Wurk.configure_client(&)
+    def configure_embed(&) = Wurk.configure_embed(&)
+    def default_configuration = Wurk.default_configuration
+    def redis(&) = Wurk.redis(&)
+    def redis_pool = Wurk.redis_pool
+    def logger = Wurk.logger
+    def server? = Wurk.server?
+    def pro? = Wurk.pro?
+    def ent? = Wurk.ent?
+    def default_job_options = Wurk.default_job_options
+
+    def default_job_options=(hash)
+      Wurk.default_job_options = hash
+    end
+
+    def strict_args!(mode = :raise) = Wurk.strict_args!(mode)
+    def testing!(mode = :fake, &) = Wurk.testing!(mode, &)
+    def testing? = Wurk.testing?
+    def load_json(str) = Wurk.load_json(str)
+    def dump_json(obj) = Wurk.dump_json(obj)
+  end
+end

data/lib/wurk/component.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'securerandom'
+
+module Wurk
+  # Shared mixin for runtime components (Launcher, Manager, Processor, Fetcher,
+  # Scheduler, Cron). Wraps clock readings, identity, thread spawning,
+  # lifecycle event dispatch, and exception forwarding so each component
+  # stays single-purpose.
+  #
+  # Host class must expose `#config` returning either a Wurk::Configuration
+  # or a Wurk::Capsule — both duck-type the methods we delegate to.
+  #
+  # Spec: docs/target/sidekiq-free.md §11 (Sidekiq::Component).
+  module Component
+    DEFAULT_THREAD_PRIORITY = -1
+
+    # Stable for the life of the process — survives fork (children inherit
+    # the same nonce). Identity differs across forks because Process.pid does.
+    PROCESS_NONCE = SecureRandom.hex(6)
+
+    attr_reader :config
+
+    # --- clocks ---------------------------------------------------------
+
+    def real_ms
+      ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+    end
+
+    def mono_ms
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
+    end
+
+    # --- identity -------------------------------------------------------
+
+    def tid
+      (Thread.current.object_id ^ ::Process.pid).to_s(36)
+    end
+
+    def hostname
+      ENV['DYNO'] || Socket.gethostname
+    end
+
+    def process_nonce
+      PROCESS_NONCE
+    end
+
+    def identity
+      "#{hostname}:#{::Process.pid}:#{process_nonce}"
+    end
+
+    def default_tag(dir = Dir.pwd)
+      File.basename(dir)
+    end
+
+    # --- delegated to config -------------------------------------------
+
+    def logger
+      config.logger
+    end
+
+    def redis(&)
+      config.redis(&)
+    end
+
+    def handle_exception(ex, ctx = {})
+      config.handle_exception(ex, ctx)
+    end
+
+    # --- cluster leadership --------------------------------------------
+
+    # True iff this process currently holds the cluster `dear-leader` lock.
+    # Per spec, the check is performed at call time (Wurk does not cache);
+    # callers must not poll faster than the 60s follower cadence. Returns
+    # false unconditionally when `WURK_LEADER=false` is set on the process
+    # (opt-out hot-standby). Any Redis error is swallowed → false, so a
+    # transient partition can't propagate as an exception into user code.
+    #
+    # Spec: docs/target/sidekiq-ent.md §6.1.
+    def leader?
+      return false if ENV[Wurk::Leader::OPT_OUT_ENV].to_s.downcase == 'false'
+
+      redis { |c| c.call('GET', Wurk::Leader::DEFAULT_KEY) } == identity
+    rescue StandardError
+      false
+    end
+
+    # --- thread boundaries ---------------------------------------------
+
+    # Wraps a block at a thread boundary: any unhandled exception is reported
+    # via handle_exception (so it lands in error_handlers / the log) and then
+    # re-raised. `last_words` is the component label included in the context.
+    def watchdog(last_words)
+      yield
+    rescue StandardError => e
+      handle_exception(e, { context: last_words })
+      raise
+    end
+
+    # Spawns a named thread that runs `block` under `watchdog(name)`. The
+    # parent must retain the returned Thread; otherwise GC may not, but
+    # report_on_exception is disabled so we don't double-log on death.
+    def safe_thread(name, priority: nil, &block)
+      Thread.new do
+        Thread.current.name = name
+        Thread.current.priority = priority || DEFAULT_THREAD_PRIORITY
+        Thread.current.report_on_exception = false
+        watchdog(name, &block)
+      end
+    end
+
+    # Invokes lifecycle hooks for `event`. Hooks run in registration order
+    # (or LIFO when `reverse: true`, used for teardown). A raise in one hook
+    # is reported via handle_exception and does NOT stop the next hook unless
+    # `reraise: true` (used in tests / fail-fast boot). `oneshot: true`
+    # clears the bucket after dispatch so the event can't fire twice.
+    def fire_event(event, oneshot: true, reverse: false, reraise: false)
+      bucket = config[:lifecycle_events][event]
+      return if bucket.nil? || bucket.empty?
+
+      iter = reverse ? bucket.reverse : bucket
+      iter.each { |hook| run_lifecycle_hook(hook, event, reraise) }
+      bucket.clear if oneshot
+    end
+
+    private
+
+    def run_lifecycle_hook(hook, event, reraise)
+      hook.call
+    rescue StandardError => e
+      handle_exception(e, { event: event })
+      raise if reraise
+    end
+  end
+end

data/lib/wurk/configuration.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+require 'logger'
+require_relative 'middleware/chain'
+require_relative 'capsule'
+require_relative 'context'
+require_relative 'topology'
+
+module Wurk
+  # Owns runtime knobs (concurrency, queues, timeouts, lifecycle events,
+  # error/death handlers) and the registry of Capsules. Single source of truth
+  # for everything the swarm / managers / processors need to boot.
+  #
+  # Spec: docs/target/sidekiq-free.md §4 (Sidekiq::Config).
+  class Configuration # rubocop:disable Metrics/ClassLength
+    # Mirrors Sidekiq::Config::DEFAULTS. Order and keys are part of the
+    # drop-in contract — third-party gems read @options via [] / fetch / dig.
+    DEFAULTS = {
+      labels: Set.new,
+      require: '.',
+      environment: nil,
+      concurrency: 5,
+      timeout: 25,
+      poll_interval_average: nil,
+      average_scheduled_poll_interval: 5,
+      on_complex_arguments: :raise,
+      max_iteration_runtime: nil,
+      error_handlers: [],
+      death_handlers: [],
+      lifecycle_events: {
+        startup: [],
+        quiet: [],
+        shutdown: [],
+        exit: [],
+        heartbeat: [],
+        beat: [],
+        leader: []
+      },
+      dead_max_jobs: 10_000,
+      dead_timeout_in_seconds: 180 * 24 * 60 * 60,
+      reloader: proc { |&b| b.call },
+      backtrace_cleaner: ->(bt) { bt },
+      logged_job_attributes: %w[bid tags],
+      redis_idle_timeout: nil
+    }.freeze
+
+    LIFECYCLE_EVENTS = %i[startup quiet shutdown exit heartbeat beat leader].freeze
+    DEFAULT_THREAD_PRIORITY = -1
+
+    # Default error handler. Wraps the report in the thread-local
+    # Wurk::Context so logger formatters/JSON layouts can pick up jid/bid/tags.
+    # `full_message` (with backtrace) in dev/debug, `detailed_message` in prod —
+    # mirrors the Sidekiq behavior so log scrapers built for one work for both.
+    #
+    # Spec: docs/target/sidekiq-free.md §4.3.
+    ERROR_HANDLER = lambda do |ex, ctx, cfg = Wurk.configuration|
+      safe_ctx = ctx || {}
+      Wurk::Context.with(safe_ctx) do
+        dev = $DEBUG || ENV['WURK_DEBUG'] || cfg.logger.debug?
+        msg = dev ? ex.full_message : ex.detailed_message
+        cfg.logger.info { msg }
+      end
+    end
+
+    attr_reader :capsules, :directory, :redis_config
+    attr_accessor :thread_priority
+
+    # Pro parity: callable that builds the statsd / dogstatsd client.
+    # Invoked once per process AFTER fork; see Wurk::Metrics::Statsd.client.
+    # Assignable as a Proc, lambda, or any object responding to #call:
+    #
+    #   config.dogstatsd = -> { Datadog::Statsd.new('host', 8125) }
+    #
+    # Spec: docs/target/sidekiq-pro.md §9.1.
+    attr_accessor :dogstatsd
+
+    def initialize(options = {})
+      @options = deep_dup_defaults.merge(options)
+      @options[:error_handlers] << ERROR_HANDLER if @options[:error_handlers].empty?
+      @capsules = {}
+      @directory = {}
+      @client_chain = Middleware::Chain.new
+      @server_chain = Middleware::Chain.new
+      @redis_config = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
+      @logger = nil
+      @thread_priority = DEFAULT_THREAD_PRIORITY
+      @frozen = false
+    end
+
+    # --- Hash-like options access -----------------------------------------
+
+    def [](key) = @options.[](key)
+
+    def []=(key, val)
+      guard_frozen!
+      @options[key] = val
+    end
+
+    def fetch(*, &) = @options.fetch(*, &)
+    def key?(key) = @options.key?(key)
+    alias has_key? key?
+    def merge!(other)
+      guard_frozen!
+      @options.merge!(other)
+    end
+
+    def dig(*keys) = @options.dig(*keys)
+
+    # --- Default capsule shortcuts ---------------------------------------
+
+    def concurrency = default_capsule.concurrency
+
+    def concurrency=(val)
+      default_capsule.concurrency = val
+    end
+
+    def queues = default_capsule.queues
+
+    def queues=(val)
+      default_capsule.queues = val
+    end
+
+    def total_concurrency
+      @capsules.each_value.sum(&:concurrency)
+    end
+
+    def default_capsule(&)
+      capsule('default', &)
+    end
+
+    def capsule(name)
+      name = name.to_s
+      cap = @capsules[name] ||= Capsule.new(name, self)
+      yield cap if block_given?
+      cap
+    end
+
+    # --- Middleware -------------------------------------------------------
+
+    def client_middleware
+      yield @client_chain if block_given?
+      @client_chain
+    end
+
+    def server_middleware
+      yield @server_chain if block_given?
+      @server_chain
+    end
+
+    # --- Redis ------------------------------------------------------------
+
+    def redis=(hash)
+      guard_frozen!
+      @redis_config = @redis_config.merge(hash.transform_keys(&:to_sym))
+    end
+
+    def redis_pool
+      default_capsule.redis_pool
+    end
+
+    def local_redis_pool
+      @local_redis_pool ||= build_redis_pool(size: 10, name: 'internal')
+    end
+
+    # Disconnect and drop every cached pool — the per-capsule mains plus
+    # the config-level internal pool. Used by Wurk::Swarm so the parent
+    # never leaks sockets into forks and each child can build fresh ones.
+    def reset_redis_pools!
+      @capsules.each_value(&:reset_redis_pools!)
+      @local_redis_pool&.disconnect!
+      @local_redis_pool = nil
+    end
+
+    def new_redis_pool(size, name = 'custom')
+      build_redis_pool(size: size, name: name)
+    end
+
+    def redis(&)
+      redis_pool.with(&)
+    end
+
+    # --- Service locator (extension registry) ----------------------------
+
+    def register(name, instance)
+      guard_frozen!
+      @directory[name] = instance
+    end
+
+    def lookup(name, default_class = nil)
+      @directory[name] ||= default_class&.new
+    end
+
+    # --- Handlers ---------------------------------------------------------
+
+    def error_handlers
+      @options[:error_handlers]
+    end
+
+    def death_handlers
+      @options[:death_handlers]
+    end
+
+    def average_scheduled_poll_interval=(interval)
+      @options[:average_scheduled_poll_interval] = interval
+    end
+
+    # --- Periodic (Cron) registration ------------------------------------
+
+    # Yields a Wurk::Cron::Manager so the host app can register periodic
+    # jobs at boot. Manager state is shared per-process so multiple
+    # `config.periodic` blocks accumulate (matches Sidekiq Ent §2.1).
+    #
+    # Spec: docs/target/sidekiq-ent.md §2.
+    def periodic
+      require_relative 'cron'
+      @periodic_manager ||= Wurk::Cron::Manager.new(self)
+      yield @periodic_manager if block_given?
+      @periodic_manager
+    end
+
+    # --- Web dashboard ----------------------------------------------------
+
+    # Web UI configuration: the authorization hook and read-only mode. Returns
+    # the process-wide `Wurk::Web.config` singleton so `config.web.read_only =
+    # true` and the engine middleware share one source of truth. Lazy-requires
+    # the web layer to keep standalone boot lean.
+    #
+    # Spec: docs/target/sidekiq-ent.md §9.2.
+    def web
+      require_relative 'web/config'
+      Wurk::Web.config
+    end
+
+    # --- K8s liveness/readiness probes -----------------------------------
+
+    # Opt-in thin HTTP listener inside the worker process for k8s probes.
+    # When called, the Launcher will start a TCP server on `port` bound to
+    # `bind` exposing `GET /live` (200 while not stopping) and `GET /ready`
+    # (200 only when Redis is reachable AND heartbeat fired within
+    # `ready_window` seconds).
+    #
+    # Off by default — call this in a `configure_server` block to enable.
+    # Spec: docs/target/sidekiq-ent.md §7.1.2.
+    def health_check(port:, bind: '0.0.0.0', ready_window: 30)
+      guard_frozen!
+      p = Integer(port)
+      rw = Integer(ready_window)
+      raise ArgumentError, 'port must be between 0 and 65535' unless (0..65535).cover?(p)
+      raise ArgumentError, 'ready_window must be > 0' unless rw.positive?
+
+      b = bind.to_s
+      raise ArgumentError, 'bind must be a non-empty string' if b.empty?
+
+      @options[:health_check_options] = { port: p, bind: b, ready_window: rw }
+    end
+
+    # --- Lifecycle hooks --------------------------------------------------
+
+    def on(event, &block)
+      raise ArgumentError, "block required for on(#{event.inspect})" unless block
+      unless LIFECYCLE_EVENTS.include?(event)
+        raise ArgumentError, "invalid event #{event.inspect}, must be one of #{LIFECYCLE_EVENTS.inspect}"
+      end
+
+      @options[:lifecycle_events][event] << block
+    end
+
+    # --- Logger -----------------------------------------------------------
+
+    def logger
+      @logger ||= default_logger
+    end
+
+    attr_writer :logger
+
+    def handle_exception(ex, ctx = {})
+      if error_handlers.empty?
+        logger.error("#{ctx} #{ex.class}: #{ex.message}")
+      else
+        error_handlers.each do |handler|
+          handler.call(ex, ctx, self)
+        rescue StandardError => e
+          logger.error("error_handler raised: #{e.class}: #{e.message}")
+        end
+      end
+    end
+
+    # --- Configure blocks (Sidekiq.configure_server / _client) -----------
+
+    def configure_server(&block)
+      yield self if block && server?
+    end
+
+    def configure_client(&block)
+      yield self if block && !server?
+    end
+
+    def server?
+      @options[:server] == true
+    end
+
+    # Worker topology for the swarm. When the host hasn't declared one (the
+    # railtie path), default to a single flat fork running the default
+    # capsule's queues + concurrency. Assign a custom Wurk::Topology (via
+    # `topology=`) for specialized slots.
+    def topology
+      @topology ||= default_topology
+    end
+
+    def topology=(value)
+      guard_frozen!
+      @topology = value
+    end
+
+    def freeze!
+      return self if @frozen
+
+      @capsules.each_value(&:freeze)
+      @capsules.freeze
+      @options.freeze
+      @directory.freeze
+      @frozen = true
+      self
+    end
+
+    def frozen?
+      @frozen
+    end
+
+    def inspect
+      "#<#{self.class} capsules=#{@capsules.keys} concurrency=#{total_concurrency}>"
+    end
+
+    private
+
+    # One flat fork running the default capsule's queues + concurrency. The
+    # railtie boots this when a Rails host mounts the engine without declaring
+    # a topology. queue_specs (not queues) so weights survive the round-trip.
+    def default_topology
+      cap = default_capsule
+      Wurk::Topology.flat(count: 1, queues: cap.queue_specs, concurrency: cap.concurrency)
+    end
+
+    def guard_frozen!
+      raise FrozenError, 'Wurk::Configuration is frozen' if @frozen
+    end
+
+    def deep_dup_defaults
+      DEFAULTS.each_with_object({}) do |(k, v), h|
+        h[k] = case v
+               when Hash then v.transform_values { |inner| inner.respond_to?(:dup) ? inner.dup : inner }
+               when Array, Set then v.dup
+               else v
+               end
+      end
+    end
+
+    def default_logger
+      logger = Wurk::Logger.new($stdout)
+      logger.level = ::Logger::INFO
+      logger
+    end
+
+    def build_redis_pool(size:, name:)
+      RedisPool.new(
+        size: size,
+        url: @redis_config[:url] || RedisPool::DEFAULT_URL,
+        timeout: @redis_config[:timeout] || RedisPool::DEFAULT_TIMEOUT,
+        name: name
+      )
+    end
+  end
+end

data/lib/wurk/context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Thread-local logging context. Job state (jid, bid, tags, elapsed, …) is
+  # attached here so loggers, middleware, and error handlers can pick it up
+  # without threading the hash through every call. Storage lives in
+  # `Thread.current[:wurk_context]` — never share across threads or forks.
+  #
+  # Spec: docs/target/sidekiq-free.md §29.
+  module Context
+    KEY = :wurk_context
+
+    # Run `block` with `hash` merged onto the thread-local context. The prior
+    # context is restored on exit, even if the block raises — safe to nest.
+    def self.with(hash)
+      prior = Thread.current[KEY]
+      Thread.current[KEY] = (prior || {}).merge(hash)
+      yield
+    ensure
+      Thread.current[KEY] = prior
+    end
+
+    # Add a single key to the current thread's context. Creates the hash
+    # if no enclosing `with` block has been opened yet.
+    def self.add(key, value)
+      Thread.current[KEY] ||= {}
+      Thread.current[KEY][key] = value
+    end
+
+    # Read the current thread's context (or an empty hash if unset).
+    def self.current
+      Thread.current[KEY] || {}
+    end
+  end
+end