wurk 1.8.0 → 1.9.0

data/lib/wurk/metrics/statsd.rb

@@ -164,6 +164,14 @@ module Wurk
           # into a JobRetry::Skip, and a job cut by its deadline passes through
           # before Middleware::Expiry books it `expired` — both sit outside this
           # middleware, and without this arm either one emits `jobs.failure`.
+          # Their registrations are
+          # `Wurk.configuration.server_middleware.prepend(Wurk::Middleware::InterruptHandler)`
+          # (lib/wurk/middleware/interrupt_handler.rb:50) and
+          # `Wurk.configuration.server_middleware.add(Wurk::Middleware::Expiry)`
+          # (lib/wurk/middleware/expiry.rb:111); this middleware is added at
+          # `Wurk.configuration.server_middleware.add(Wurk::Metrics::Statsd)`
+          # (lib/wurk.rb:351), after Limiter's add at lib/wurk.rb:335 and before
+          # History's add at lib/wurk.rb:358.
           # Pro's statsd emitter is closed source, so the oracle is the free
           # ExecutionTracker plus the rule that the two Wurk emitters must never
           # classify one event differently. Signed off in

data/lib/wurk/middleware/chain.rb

@@ -7,7 +7,13 @@ module Wurk
     # pushes to index 0, `insert_before`/`insert_after` anchor relative to an
     # existing entry, `invoke` walks the chain handing the inner block to each.
     #
-    # Entries store klass + ctor args, not the live object: every job gets a
+    # `add` has one opt-in exception, declared per middleware class: a class
+    # may name the classes it must stay OUTSIDE of in a class-level `outer_of`,
+    # and `add` then places it before the first of those anchors instead of at
+    # the tail. A class that declares no anchor keeps the plain append.
+    #
+    # Entries store klass + ctor args + the config they were registered with,
+    # not the live object: every job gets a
     # fresh instance per entry (`invoke` builds each as it reaches it, `retrieve`
     # builds them all up front). This keeps middleware thread-safe by
     # construction and matches Sidekiq's lifecycle.
@@ -19,20 +25,28 @@ module Wurk
       attr_reader :entries
       attr_accessor :config
 
-      def initialize(config = nil)
+      def initialize(config = nil, on_registration: nil)
         @config = config
+        @on_registration = on_registration
         @entries = []
         yield self if block_given?
       end
 
       def each(&) = @entries.each(&)
 
-      # Bind a duplicate of this chain to `capsule`. Capsules share the parent
-      # config's entries by reference initially but mutate independently after
-      # the first `add`/`remove`/etc. (Array#dup on `@entries`).
+      # Bind a duplicate of this chain to `capsule`. Entries carry their
+      # config, so each is duplicated and only the duplicate rebound: the
+      # capsule's middleware resolve the capsule while the parent's entries
+      # keep the parent config. Array#dup on `@entries` keeps the two chains
+      # independent after the first `add`/`remove`/etc.
       def copy_for(capsule)
         copy = dup
         copy.instance_variable_set(:@config, capsule)
+        copy.entries.map! do |entry|
+          rebound = entry.dup
+          rebound.config = capsule
+          rebound
+        end
         copy
       end
 
@@ -40,26 +54,65 @@ module Wurk
         @entries.delete_if { |entry| entry.klass == klass }
       end
 
+      # Appends the middleware — the documented Sidekiq behaviour (spec
+      # §10.1): any existing entry for `klass` is removed and the new one
+      # lands at the tail (innermost).
+      #
+      # One opt-in exception, declared per class: a middleware may name the
+      # classes it must stay OUTSIDE of in a class-level `outer_of`. When one
+      # of those anchors is registered, the entry is placed before the first
+      # of them instead of at the tail — so re-registering such a middleware
+      # cannot silently move it inside the middleware it depends on being
+      # outside of. A class that declares no anchor keeps the plain append.
+      #
+      # An entry already registered before the anchor keeps its slot (only
+      # its ctor args are refreshed): moving it would be a relocation the
+      # caller did not ask for.
       def add(klass, *)
+        @on_registration&.call(klass)
+        entry = make_entry(klass, *)
+        anchors = anchor_classes(klass)
+        existing = @entries.index { |e| e.klass == klass }
+        anchor = @entries.index { |e| anchors.include?(e.klass) }
+
+        # No anchor registered: remove the old entry, append at the tail.
+        if anchor.nil?
+          remove(klass)
+          @entries << entry
+          return @entries
+        end
+
+        # Already outside the anchor: keep the slot, refresh the entry.
+        if existing && existing < anchor
+          @entries[existing] = entry
+          return @entries
+        end
+
+        # Registered inside the anchor (or not registered at all): move it
+        # out, to just before the first anchor.
         remove(klass)
-        @entries << Entry.new(klass, *)
+        @entries.insert(anchor, entry)
+        @entries
       end
 
       def prepend(klass, *)
+        @on_registration&.call(klass)
         remove(klass)
-        @entries.unshift(Entry.new(klass, *))
+        @entries.unshift(make_entry(klass, *))
       end
 
       def insert_before(oldklass, newklass, *)
+        @on_registration&.call(newklass)
         i = @entries.index { |entry| entry.klass == newklass }
-        new_entry = i.nil? ? Entry.new(newklass, *) : @entries.delete_at(i)
+        new_entry = i.nil? ? make_entry(newklass, *) : @entries.delete_at(i)
         i = @entries.index { |entry| entry.klass == oldklass } || 0
         @entries.insert(i, new_entry)
       end
 
       def insert_after(oldklass, newklass, *)
+        @on_registration&.call(newklass)
         i = @entries.index { |entry| entry.klass == newklass }
-        new_entry = i.nil? ? Entry.new(newklass, *) : @entries.delete_at(i)
+        new_entry = i.nil? ? make_entry(newklass, *) : @entries.delete_at(i)
         i = @entries.index { |entry| entry.klass == oldklass } || (@entries.size - 1)
         @entries.insert(i + 1, new_entry)
       end
@@ -74,7 +127,7 @@ module Wurk
       end
 
       def retrieve
-        map { |entry| entry.make_new(@config) }
+        map(&:make_new)
       end
 
       def clear
@@ -101,7 +154,7 @@ module Wurk
       def traverse(entries, index, args, &block)
         return yield if index == entries.size
 
-        entries[index].make_new(@config).call(*args) do
+        entries[index].make_new.call(*args) do
           traverse(entries, index + 1, args, &block)
         end
       end
@@ -111,6 +164,24 @@ module Wurk
       def initialize_copy(orig)
         super
         @entries = orig.entries.dup
+        @on_registration = nil
+      end
+
+      # The ordering anchors a middleware class declares, if any: a class-level
+      # `outer_of` returning the classes it must stay OUTSIDE of. Empty when
+      # the class declares none — the plain Sidekiq append.
+      def anchor_classes(klass)
+        return [] unless klass.respond_to?(:outer_of)
+
+        Array(klass.outer_of)
+      end
+
+      # Registration binds the entry to this chain's config/capsule so that
+      # `Entry#make_new` can stay zero-argument (spec §10.1).
+      def make_entry(klass, *)
+        entry = Entry.new(klass, *)
+        entry.config = @config
+        entry
       end
 
       # Holds the klass + ctor args for a registered middleware. Defers
@@ -127,6 +198,7 @@ module Wurk
       # a class that does not declare it still gets asked.
       class Entry
         attr_reader :klass
+        attr_accessor :config
 
         def initialize(klass, *args)
           @klass = klass
@@ -134,9 +206,9 @@ module Wurk
           @takes_config = klass.public_method_defined?(:config=)
         end
 
-        def make_new(config = nil)
+        def make_new
           instance = @klass.new(*@args)
-          instance.config = config if config && (@takes_config || instance.respond_to?(:config=))
+          instance.config = config if @takes_config || instance.respond_to?(:config=)
           instance
         end
       end

data/lib/wurk/pool_checkout.rb

@@ -9,7 +9,7 @@ module Wurk
   # after a command may already have applied server-side (see RedisPool#with).
   # The object behind a wrapper is not always ours, though: the Sidekiq surface
   # Wurk drops into lets a host supply any ConnectionPool-shaped object
-  # (`Sidekiq::Client#redis_pool=`, `Sidekiq::Web.redis_pool=`, the `pool:`
+  # (`Sidekiq::Client#redis_pool=`, the `pool:`
   # kwarg on Stats::History / Deploy / Leader / Profiler / Metrics::History),
   # and a bare `def with; yield conn; end` decorator — the shape people reach
   # for to count or trace round trips — is a legal implementation of it. Handing

data/lib/wurk/queue_slot.rb

@@ -65,15 +65,25 @@ module Wurk
   #     of, and it is why a live holder has to keep saying so — {HELD} is the
   #     ledger the heartbeat refreshes from (see {refresh_in}).
   #
-  # A rolling restart is the one case where a queue can briefly run over its
-  # cap: `Swarm::Restart` boots the replacement before it TERMs the old child,
-  # so for the length of one drain both generations hold slots. That is
-  # deliberate and left alone. Fixing it would mean either starving the
-  # replacement until the old child's last job finished — the deploy stalls
-  # behind the slowest job on the queue — or handing capacity between processes,
-  # which needs the counter this ledger exists to avoid. The excess is bounded
-  # by the old child's in-flight count, lasts at most one `drain_timeout`, and
-  # is TTL-bounded even if that child is SIGKILLed instead of draining.
+  # A rolling restart does not run a queue over its cap. `Swarm::Restart` boots
+  # the replacement before it TERMs the old child, but both generations' holds
+  # are members of the one ZSET and `fetch_slot.lua` refuses a fresh claim once
+  # its ZCARD reaches capacity — so the overlap throttles the replacement. The
+  # ledger stays honest through the drain: a quieted child keeps beating
+  # (Launcher#quiet deliberately leaves the heartbeat running), so its holds
+  # stay refreshed until each job's own release takes it off. The one hold
+  # that leaves while its job is still in flight is the drain-deadline
+  # hand-back — a drain that overruns its deadline bulk-requeues the payload
+  # and raises `Wurk::Shutdown`, and the unwind's `ensure` reaches
+  # `UnitOfWork#release_slot` while the job is still unwinding. That is a
+  # slot-for-slot hand-back, not an extra admission: the re-run spends the
+  # freed capacity on its own fresh admission. A child SIGKILLed instead of
+  # draining releases nothing, so its holds stay counted until the TTL
+  # reclaims them — a refusal window, at most one `drain_timeout` or
+  # {TTL_SECONDS} long, never an over-run. What remains deliberate: booting
+  # the replacement warm instead of starving it behind the old child's last
+  # job, and never handing capacity between processes — that would need the
+  # counter this ledger exists to avoid.
   module QueueSlot
     # How long a hold survives with nobody refreshing it. Deliberately the same
     # as `Heartbeat::TTL_SECONDS` (pinned by a test): a hold is refreshed on the

data/lib/wurk/rails_boot.rb

@@ -18,9 +18,10 @@ module Wurk
     # Invoked from the `wurk.server_mode` initializer, before config/initializers
     # load. This Rails process forks the workers, so it IS the server. Enter
     # server mode now — otherwise the app's `Sidekiq.configure_server` blocks
-    # gate on `config.server?` (still false) and are silently dropped. A process
-    # that won't run workers (skip_boot?, or one that refuses to boot under a
-    # preforking web server) is not a server.
+    # gate on `config.server?` (still false) and are dropped, each skip logging
+    # one WARN naming the gate (`configure_server` / `server? is false`). A
+    # process that won't run workers (skip_boot?, or one that refuses to boot
+    # under a preforking web server) is not a server.
     #
     # It is a client as well: its web requests enqueue, so the app's
     # `Sidekiq.configure_client` blocks (client middleware, the client's Redis)
@@ -68,17 +69,27 @@ module Wurk
     # custom script that requires config/environment — and a denylist can
     # never name them all: each one forked a full swarm that fetched jobs, and
     # its at_exit drain then cut those jobs off when the one-off command
-    # finished. The markers are constants only a running server defines
-    # (Bundler.require of the puma gem loads `Puma`, never `Puma::Launcher`).
+    # finished. The markers are constants only a running server defines.
     # Any other server (Falcon, Thin, Pitchfork, a bespoke rackup) opts in
     # with WURK_EMBED=1.
     def serving?
       return true if ENV['WURK_EMBED'] == '1'
-      return true if defined?(::Rails::Server) || defined?(::Puma::Launcher) || defined?(::PhusionPassenger)
+      return true if defined?(::Rails::Server) || puma_launcher_loaded? || defined?(::PhusionPassenger)
 
       unicorn_server?
     end
 
+    # Bundler.require of the puma gem defines `Puma` in every process, and
+    # puma >= 6 registers `autoload :Launcher` in lib/puma.rb — `defined?`
+    # reports an autoload as "constant" without loading it, so the bare check
+    # was true in `rails runner` / a console and forked a swarm there. Only a
+    # running server has actually loaded the launcher.
+    def puma_launcher_loaded?
+      return false unless defined?(::Puma::Launcher)
+
+      !::Puma.autoload?(:Launcher)
+    end
+
     # `require 'unicorn'` (a Gemfile entry) defines the constant in every
     # process, so the program name is what tells the server apart.
     def unicorn_server?

data/lib/wurk/railtie.rb

@@ -18,11 +18,15 @@ module Wurk
     # @@options, so `Rails.application.config.wurk` reads back the same object.
     config.wurk = ::ActiveSupport::OrderedOptions.new
 
-    # Enter server mode BEFORE config/initializers load — otherwise the app's
-    # `Sidekiq.configure_server` blocks gate on `config.server?` (still false)
-    # and are silently dropped. RailsBoot decides whether this process serves.
+    # The gemspec ships no .rake files, so the railtie loads Wurk's
+    # host-facing rake tasks itself for `bin/rails wurk:import:cron` to exist.
     rake_tasks { load File.expand_path('rake_tasks.rb', __dir__) }
 
+    # Enter server mode BEFORE config/initializers load — otherwise the app's
+    # `Sidekiq.configure_server` blocks gate on `config.server?` (still false)
+    # and are dropped, each skip logging one WARN naming the gate
+    # (`configure_server` / `server? is false`). RailsBoot decides whether this
+    # process serves.
     initializer 'wurk.server_mode', before: :load_config_initializers do |app|
       Wurk::RailsBoot.enter_server_mode_if_serving(app)
     end

data/lib/wurk/redis_connection.rb

@@ -5,11 +5,13 @@ require_relative 'redis_pool'
 module Wurk
   # Sidekiq-compatible pool constructor. `Sidekiq::RedisConnection.create(...)`
   # is the documented way to build a standalone Redis pool (spec §26) — it's the
-  # default pool for `Sidekiq::Deploy` (§23) and the constructor for per-shard
-  # pools in multi-shard web mounts (Pro §10.2). Returns a `Wurk::RedisPool`
+  # default pool for `Sidekiq::Deploy` (§23). Returns a `Wurk::RedisPool`
   # (connection_pool-backed, redis-client adapter), which is `.with`-compatible
   # with everything that expects a Sidekiq pool.
   #
+  # Pro §10.2 pool-bound multi-shard web mounts (`Sidekiq::Pro::Web.with`) are
+  # unsupported: `Wurk::Web` has no `.with` factory.
+  #
   # Accepts Sidekiq's option keys (`url`, `size`, `pool_timeout`, `pool_name`,
   # and `name` — the Sentinel master next to `sentinels:`) plus the socket
   # knobs (`connect_timeout`/`read_timeout`/`write_timeout`/

data/lib/wurk/unique.rb

@@ -98,9 +98,12 @@ module Wurk
         @enabled == true
       end
 
-      def enable!
+      # `config` selects the chains and death handlers, installed once each;
+      # the enabled flag remains process-global, including for other configs
+      # whose chains already carry the middleware.
+      def enable!(config = Wurk.configuration)
         @enabled = true
-        register_middleware!
+        register_middleware!(config)
         true
       end
 
@@ -188,12 +191,12 @@ module Wurk
         nil
       end
 
-      def register_middleware!
-        Wurk.configuration.client_middleware.add(ClientMiddleware) \
-          unless Wurk.configuration.client_middleware.exists?(ClientMiddleware)
-        Wurk.configuration.server_middleware.add(ServerMiddleware) \
-          unless Wurk.configuration.server_middleware.exists?(ServerMiddleware)
-        handlers = Wurk.configuration.death_handlers
+      def register_middleware!(config)
+        client_chain = config.client_middleware
+        server_chain = config.server_middleware
+        client_chain.add(ClientMiddleware) unless client_chain.exists?(ClientMiddleware)
+        server_chain.add(ServerMiddleware) unless server_chain.exists?(ServerMiddleware)
+        handlers = config.death_handlers
         handlers << DEATH_HANDLER unless handlers.include?(DEATH_HANDLER)
       end
     end

data/lib/wurk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wurk
-  VERSION = '1.8.0'
+  VERSION = '1.9.0'
 end

data/lib/wurk/web/config.rb

@@ -129,7 +129,9 @@ module Wurk
       # (the default) out of localStorage; this is what it falls back to for a
       # visitor who has never picked one. Injected ahead of the shell's
       # pre-paint script so a host default paints with everything else instead
-      # of flashing the other palette. nil emits nothing.
+      # of flashing the other palette. nil emits nothing. Initialization and
+      # reset! sample WURK_WEB_DEFAULT_THEME through the validating writer;
+      # later explicit assignments (including nil) override that seed.
       attr_reader :default_theme
 
       def default_theme=(value)
@@ -163,7 +165,16 @@ module Wurk
       # Keyed rather than flat because the negotiated hint is not the last
       # word — a `?locale=` link or a stored pick outranks it — so the entry
       # has to be chosen in the browser, against the locale actually rendered.
-      attr_accessor :translations
+      attr_reader :translations
+
+      def translations=(value)
+        raise ArgumentError, "translations must be a Hash (got #{value.class})" unless value.is_a?(::Hash)
+
+        value.each do |locale, copy|
+          validate_translation_hash!(copy, "translations[#{locale.inspect}]")
+        end
+        @translations = value
+      end
 
       # Registers a `(env, method, path) -> truthy/falsey` block. Re-calling
       # overwrites; the spec exposes a single hook, not a chain.
@@ -250,8 +261,8 @@ module Wurk
       # that wraps the dashboard, in front of the authorization hook, so a
       # host app can gate the UI with Devise/Warden/Sorcery/Rack::Auth::Basic
       # without writing its own middleware. `args` and an optional block pass
-      # straight through to the middleware's `new`. Call before the first
-      # request (i.e. from an initializer) — the chain is built once.
+      # straight through to the middleware's `new`. Each inner app's chain is
+      # cached until the middleware configuration changes.
       def use(middleware, *args, &block)
         @middlewares << [middleware, args, block]
       end
@@ -263,13 +274,15 @@ module Wurk
       # on one evict the other's chain. The snapshot matters because
       # `middlewares` is the live array (upstream surface): direct mutation
       # after the first request triggers a rebuild instead of silently serving
-      # the stale chain. Steady state is one Hash lookup plus an == over a
-      # handful of entries.
+      # the stale chain. Copy triples and positional-argument lists so edits
+      # cannot mutate the snapshot too; argument objects and blocks retain
+      # their identities (their internal mutations are not tracked). Steady
+      # state is one Hash lookup plus an == over a handful of entries.
       def rack_app(inner)
         snapshot, app = @rack_apps[inner]
         return app if app && snapshot == @middlewares
 
-        stack = @middlewares.dup
+        stack = middleware_snapshot
         app = ::Rack::Builder.new do
           stack.each { |middleware, args, block| use(middleware, *args, &block) }
           run inner
@@ -279,7 +292,7 @@ module Wurk
       end
 
       # Read-only mode. When on, the Authorization middleware blocks every
-      # non-GET request (retry/kill/requeue/delete/pause/resume/clear) with
+      # non-GET request (retry/kill/add_to_queue/delete/pause/unpause/clear) with
       # 403, and the SPA hides destructive actions via the /api/meta flag.
       # Defaults from WURK_WEB_READ_ONLY=1 so a viewer-only deploy (e.g. the
       # public demo) needs no Ruby config.
@@ -296,7 +309,7 @@ module Wurk
         @authorization = nil
         @read_only = env_read_only?
         @read_only_message = nil
-        @default_theme = nil
+        self.default_theme = ENV.fetch('WURK_WEB_DEFAULT_THEME', nil)
         @max_streams = nil
         @middlewares = []
         @rack_apps = {}.compare_by_identity
@@ -316,6 +329,26 @@ module Wurk
 
       private
 
+      def middleware_snapshot
+        @middlewares.map { |middleware, args, block| [middleware, args.dup, block] }
+      end
+
+      def validate_translation_hash!(copy, path)
+        raise ArgumentError, "#{path} must be a Hash (got #{copy.class})" unless copy.is_a?(::Hash)
+
+        copy.each do |key, value|
+          child_path = "#{path}[#{key.inspect}]"
+          case value
+          when ::Hash
+            validate_translation_hash!(value, child_path)
+          when ::String
+            next
+          else
+            raise ArgumentError, "#{child_path} must be a String or Hash (got #{value.class})"
+          end
+        end
+      end
+
       def env_read_only?
         ENV['WURK_WEB_READ_ONLY'] == '1'
       end

data/lib/wurk/web/enterprise.rb

@@ -198,9 +198,10 @@ module Wurk
         end
 
         # Global top-N rollup. Wraps `Query.top_jobs` and keeps the wire
-        # shape of `[[class_name, {p:, f:, ms:}], ...]`.
-        def top(minutes: 60, class_filter: nil)
-          Wurk::Metrics::Query.top_jobs(minutes: minutes, class_filter: class_filter)
+        # shape of `[[class_name, {p:, f:, ms:}], ...]`. `hours:` reads the
+        # 10-minute buckets instead of the per-minute ones.
+        def top(minutes: 60, hours: nil, class_filter: nil)
+          Wurk::Metrics::Query.top_jobs(minutes: minutes, hours: hours, class_filter: class_filter)
         end
 
         # Cluster-total time-series for the dashboard charts. `bucket` is