wurk 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be0f3ba28a3db0217dc5a1a99eff9e0d2154eafb6e7a1b2c005df1c479ef7156
-  data.tar.gz: 69aff128e339a14b77e8e28927bd5c1168eaf308ff1b4d08b27b215bb4d24a76
+  metadata.gz: 2b1f8eac5cefbd9f645598b9a37dca543aeebb361967d820f369cc14420ad3f6
+  data.tar.gz: 813958b643c78cdd2ffa5063798bb3994f6510b1b0d50a0a54db1622f3bb325a
 SHA512:
-  metadata.gz: 505ff2863233ddfd349bc28a213cebf91e8d81d6146d68306304aca78235fba82a55061d9e67db6e97ca2638ed61f184ef36f97152035c1c4d2d32b06cd85cae
-  data.tar.gz: b60e5455d8352e4e16aa6d025c70253dff1af1637dfc73ca244781e22059efd8201a826afc6c441638e062db6d5b84987036c885b9d5451d68aab05ac0583522
+  metadata.gz: 65ca6b60bf079d626f3887d9e1e12b7d1d1f91ab264c5fcba7c77f54667961159fb8a63c8be89d44e9583ef7c264669e546eb15ab4bc13e392ef85b35dfea6ad
+  data.tar.gz: b865d8cd28483589bad0f6d879d80a85c9f9d5cb9b79a494634c90ebaf0f5371169ed7012303dabdc736b32be3596dbffd2ac60b2bbeb3d24c1b40514e483b54

data/lib/wurk/configuration.rb

@@ -6,6 +6,7 @@ require_relative 'middleware/chain'
 require_relative 'capsule'
 require_relative 'context'
 require_relative 'topology'
+require_relative 'redis_options'
 
 module Wurk
   # Owns runtime knobs (concurrency, queues, timeouts, lifecycle events,
@@ -169,8 +170,14 @@ module Wurk
 
     # --- Redis ------------------------------------------------------------
 
+    # Validated here, in the process running the initializer, rather than later
+    # in whichever process first builds a pool. The swarm's children are the ones
+    # that construct pools, so a bad key used to kill every child on boot while
+    # the parent stayed up and healthy — Running pod, passing probe, zero jobs
+    # processed (#283).
     def redis=(hash)
       guard_frozen!
+      RedisOptions.validate!(hash)
       @redis_config = @redis_config.merge(hash.transform_keys(&:to_sym))
     end
 

data/lib/wurk/redis_options.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'redis-client'
+
+module Wurk
+  # Translates a Sidekiq-shaped `config.redis` hash into the exact keyword set
+  # redis-client accepts.
+  #
+  # Sidekiq normalizes the hash itself before handing it over
+  # (`sidekiq/redis_client_adapter.rb#client_opts`), so initializers in the wild
+  # carry keys redis-client has never known. Wurk used to splat the hash straight
+  # into `RedisClient.config`, which surfaced as
+  # `ArgumentError: unknown keyword: :network_timeout` — and only inside the
+  # forked children, which build their own pools (#283). The parent booted fine,
+  # the liveness probe passed, and the swarm respawn loop churned forever
+  # processing zero jobs. Hence `validate!`, called from Configuration#redis= so
+  # a bad hash raises in the parent where someone can actually see it.
+  #
+  # Reference: sidekiq 7.3 / 8.1 `client_opts` — namespace rejected,
+  # size/pool_timeout dropped, `network_timeout` → `timeout`, `master_name` →
+  # `name`, role/driver symbolized, `reconnect_attempts ||= 1`.
+  module RedisOptions
+    # Consumed by the pool layer (RedisPool / Capsule); never a socket concern.
+    POOL_KEYS = %i[size name pool_name pool_timeout on_error].freeze
+
+    # Accepted for Sidekiq parity, then dropped: Sidekiq used `logger` for its
+    # own "connecting to Redis with options ..." line and `cluster_safe` to
+    # unlock `:nodes`. redis-client has no keyword for either.
+    IGNORED_KEYS = %i[logger cluster_safe].freeze
+
+    # Sidekiq-only spellings this module rewrites into redis-client keywords.
+    TRANSLATED_KEYS = %i[network_timeout master_name].freeze
+
+    # The umbrella socket timeout, under both its names. `network_timeout` is
+    # the redis-rb-era spelling every "widen the timeouts for a slow/remote
+    # Redis" snippet still uses; `timeout` is redis-client's own.
+    UMBRELLA_TIMEOUT_KEYS = %i[network_timeout timeout].freeze
+
+    # Wurk splits the socket timeouts (#101) and passes all three explicitly, and
+    # redis-client lets an explicit `read_timeout` win over `timeout` — so
+    # forwarding the umbrella verbatim would silently drop the host's value.
+    # Fan it out instead; a host-supplied split timeout still wins over the fan-out.
+    SPLIT_TIMEOUT_KEYS = %i[connect_timeout read_timeout write_timeout].freeze
+
+    # Symbols in redis-client, strings in plenty of YAML-sourced configs.
+    SYMBOLIZED_KEYS = %i[driver role].freeze
+
+    # Keys that mean something in Sidekiq but have no Wurk equivalent. Raise
+    # naming the key and its replacement — the alternative is an opaque
+    # `unknown keyword:` from three layers down inside a forked child.
+    REJECTED_KEYS = {
+      namespace: 'Redis namespacing was dropped in Sidekiq 7 and Wurk never implemented it ' \
+                 '(docs/migrate-from-sidekiq.md §4). Give Wurk its own Redis database ' \
+                 '(redis://host:6379/1) or its own instance instead.',
+      nodes: 'Wurk does not run on Redis Cluster. Point config.redis at a single server with ' \
+             '`url:`, or at a Sentinel set with `sentinels:`.'
+    }.freeze
+
+    # Keyword parameter kinds in Method#parameters.
+    KEYWORD_PARAMS = %i[key keyreq].freeze
+
+    class << self
+      # The keyword hash for RedisClient.config / RedisClient.sentinel.
+      # `defaults` are Wurk's own socket defaults; everything the host supplied
+      # wins over them.
+      def normalize(options, defaults: {})
+        opts = symbolize(options)
+        validate!(opts)
+        opts = translate(opts)
+
+        # A default `url` is meaningless next to a sentinel set and actively
+        # harmful: SentinelConfig derives the master name and db from it.
+        defaults = defaults.except(:url) if sentinel?(opts)
+
+        defaults.merge(split_timeouts(opts), opts.except(*UMBRELLA_TIMEOUT_KEYS))
+      end
+
+      # Raises for anything redis-client would reject. Cheap and pure, so it runs
+      # in the parent (Configuration#redis=) as well as at pool-build time.
+      def validate!(options)
+        opts = symbolize(options)
+
+        REJECTED_KEYS.each do |key, hint|
+          raise ArgumentError, "config.redis[:#{key}] is not supported. #{hint}" if opts.key?(key)
+        end
+
+        unknown = opts.keys - known_keys
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "config.redis: unknown option#{'s' if unknown.size > 1} " \
+              "#{unknown.map(&:inspect).join(', ')}. Supported keys: #{known_keys.sort.join(', ')}."
+      end
+
+      # Sentinel sets go through RedisClient.sentinel — RedisClient.config
+      # rejects `sentinels:` outright. Same routing Sidekiq does.
+      def sentinel?(client_config)
+        client_config.key?(:sentinels)
+      end
+
+      # Every keyword redis-client itself accepts, read off its own signatures so
+      # the list can't drift from the installed version. Config#initialize takes
+      # a **kwargs rest and forwards to Config::Common, so both have to be walked;
+      # SentinelConfig adds the sentinel-only keys.
+      def known_keys
+        @known_keys ||= [
+          ::RedisClient::Config, ::RedisClient::Config::Common, ::RedisClient::SentinelConfig
+        ].flat_map { |mod| keyword_params(mod) }.union(POOL_KEYS, IGNORED_KEYS, TRANSLATED_KEYS)
+      end
+
+      private
+
+      # Drop what redis-client has no keyword for, then rewrite the Sidekiq
+      # spellings it does have an equivalent for.
+      def translate(opts)
+        opts = opts.except(*POOL_KEYS, *IGNORED_KEYS)
+        opts[:name] = opts.delete(:master_name) if opts.key?(:master_name)
+        SYMBOLIZED_KEYS.each { |key| opts[key] = opts[key].to_sym if opts[key] }
+        opts
+      end
+
+      def keyword_params(mod)
+        mod.instance_method(:initialize).parameters.filter_map do |kind, key|
+          key if KEYWORD_PARAMS.include?(kind)
+        end
+      end
+
+      # The umbrella timeout fanned out across the three split ones. Returns {}
+      # when the host set neither, leaving Wurk's defaults in place.
+      def split_timeouts(opts)
+        umbrella = opts.values_at(*UMBRELLA_TIMEOUT_KEYS).compact.first
+        return {} unless umbrella
+
+        SPLIT_TIMEOUT_KEYS.to_h { |key| [key, umbrella] }
+      end
+
+      def symbolize(options)
+        options.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/wurk/redis_pool.rb

@@ -3,6 +3,7 @@
 require 'redis-client'
 require 'connection_pool'
 require_relative 'redis_client_adapter'
+require_relative 'redis_options'
 
 module Wurk
   # Per-process pool over redis-client + connection_pool. Never share a socket
@@ -37,6 +38,15 @@ module Wurk
     DEFAULT_WRITE_TIMEOUT      = 2.5
     DEFAULT_RECONNECT_ATTEMPTS = 1
 
+    # The floor every pool starts from; any key the host passed wins over it.
+    DEFAULT_CLIENT_CONFIG = {
+      url: DEFAULT_URL,
+      connect_timeout: DEFAULT_CONNECT_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT,
+      reconnect_attempts: DEFAULT_RECONNECT_ATTEMPTS
+    }.freeze
+
     # Server-side messages where the connection is closed and the block retried
     # exactly once. READONLY is itself a RedisClient::ConnectionError subclass,
     # so this message match must be tested BEFORE the generic ConnectionError
@@ -60,9 +70,12 @@ module Wurk
 
     # Takes the standard Sidekiq `config.redis` hash: `pool_timeout` tunes the
     # ConnectionPool checkout; `connect_timeout`/`read_timeout`/`write_timeout`/
-    # `reconnect_attempts` plus any other key (driver, ssl_params, …) forward
-    # verbatim to RedisClient.config. `on_error` is an optional callable fired
-    # per retry / final give-up with { error:, attempt:, retried:, pool: }.
+    # `reconnect_attempts` plus any other redis-client key (driver, ssl_params,
+    # sentinels, …) reach the client. Sidekiq-only spellings (`network_timeout`,
+    # `master_name`, `logger`, …) are translated or dropped by {RedisOptions};
+    # a key redis-client would reject raises there with the key named.
+    # `on_error` is an optional callable fired per retry / final give-up with
+    # { error:, attempt:, retried:, pool: }.
     def initialize(size:, name: DEFAULT_NAME, on_error: nil, **options)
       @size          = size
       @name          = name
@@ -112,24 +125,29 @@ module Wurk
 
     private
 
-    # Socket config forwarded to RedisClient.config. Host-supplied keys win over
-    # the defaults; `pool_timeout` is dropped (it's a pool concern, not a socket
-    # one) and unknown keys pass straight through.
+    # Socket config forwarded to redis-client. RedisOptions owns the translation
+    # of the Sidekiq-shaped hash (network_timeout, master_name, pool-only keys,
+    # …) so this class stays about pooling; host-supplied keys win over the
+    # defaults.
     def build_client_config(options)
-      {
-        url: DEFAULT_URL,
-        connect_timeout: DEFAULT_CONNECT_TIMEOUT,
-        read_timeout: DEFAULT_READ_TIMEOUT,
-        write_timeout: DEFAULT_WRITE_TIMEOUT,
-        reconnect_attempts: DEFAULT_RECONNECT_ATTEMPTS
-      }.merge(options.except(:pool_timeout)).freeze
+      RedisOptions.normalize(options, defaults: DEFAULT_CLIENT_CONFIG).freeze
     end
 
     # Wrapped in the CompatClient decorator so `Sidekiq.redis { |c| c.smembers }`
     # method-style commands work like Sidekiq 7+ (#204). Wurk's own code paths
     # use #call, which the decorator forwards.
     def build_client
-      RedisClientAdapter::CompatClient.new(RedisClient.config(**@client_config).new_client)
+      RedisClientAdapter::CompatClient.new(redis_client_config.new_client)
+    end
+
+    # A Sentinel set is a different constructor, not a different keyword:
+    # `RedisClient.config(sentinels: [...])` raises. Sidekiq routes the same way.
+    def redis_client_config
+      if RedisOptions.sentinel?(@client_config)
+        RedisClient.sentinel(**@client_config)
+      else
+        RedisClient.config(**@client_config)
+      end
     end
 
     def safe_close(conn)

data/lib/wurk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wurk
-  VERSION = "1.3.0"
+  VERSION = "1.3.1"
 end

data/lib/wurk.rb

@@ -224,6 +224,22 @@ module Wurk
     def ent?
       false
     end
+
+    # Lazily loads the Rails engine the first time something asks for
+    # `Wurk::Engine`. See the note above the `require "wurk/rails"` guard at the
+    # bottom of this file for why the guard alone isn't enough (#282), and why
+    # this loads the engine and not the railtie.
+    def const_missing(name)
+      return super unless name == :Engine
+      return super unless defined?(::Rails::Engine) && defined?(::ActionDispatch::Routing::RouteSet)
+
+      require_relative 'wurk/engine'
+      # If engine.rb somehow didn't define it, fall through to the real NameError
+      # rather than recursing back into here.
+      return super unless const_defined?(:Engine, false)
+
+      const_get(:Engine, false)
+    end
   end
 end
 
@@ -318,3 +334,30 @@ require_relative 'wurk/compat'
 # real Rails host both are loaded by `rails/all` before Bundler.require, so the
 # stricter gate is invisible there.
 require_relative 'wurk/rails' if defined?(Rails::Engine) && defined?(::ActionDispatch::Routing::RouteSet)
+
+# The gate above is evaluated exactly once, when this file is first required —
+# which is too early for the standalone runners (#282). `exe/wurk` and
+# `exe/wurkswarm` require "wurk" before Rails exists (the gate is false, nothing
+# Rails-y loads), then boot the host app themselves via
+# Wurk::CLI#boot_rails_application. By then "wurk" is in $LOADED_FEATURES, so the
+# app's own `Bundler.require` is a no-op and the gate never gets a second look. A
+# host that did exactly what the README says — `mount Wurk::Engine => "/wurk"` in
+# config/routes.rb — then dies during boot with `uninitialized constant
+# Wurk::Engine`, from the worker process only. Web processes are unaffected:
+# there Bundler.require runs after railties, so the gate passes.
+#
+# `Wurk.const_missing` (defined in the class << self block above) closes that
+# window without giving up the lean standalone boot: nothing loads until
+# something actually asks for Wurk::Engine, and even then only when Rails is
+# really present. It reuses the same two-part condition as the guard above, so
+# the ecosystem carve-out (rails/engine/railties without ActionDispatch, per
+# sidekiq-cron's test helper) still falls through to a plain NameError instead of
+# crashing on `isolate_namespace`.
+#
+# It deliberately loads `wurk/engine`, not `wurk/rails`: the railtie's
+# `config.after_initialize` is a *global* ActiveSupport load hook registered at
+# require time, and routes are drawn before those hooks run — so dragging the
+# railtie in there would fork a swarm inside a `wurkswarm` parent that is about
+# to fork its own. The runner owns the swarm; the routes file only needs the
+# constant. `defined?(Wurk::Engine)` stays nil until first use, which is what the
+# "standalone stays Rails-free" tests assert.

data/vendor/assets/dashboard/wurk-manifest.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.3.0",
-  "timestamp": "2026-07-26T14:23:49.421Z"
+  "version": "1.3.1",
+  "timestamp": "2026-07-26T15:00:00.106Z"
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wurk
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - developerz.ai
@@ -270,6 +270,7 @@ files:
 - lib/wurk/railtie.rb
 - lib/wurk/redis_client_adapter.rb
 - lib/wurk/redis_connection.rb
+- lib/wurk/redis_options.rb
 - lib/wurk/redis_pool.rb
 - lib/wurk/retry_set.rb
 - lib/wurk/scheduled.rb