wurk 1.7.6 → 1.8.0

data/lib/wurk/import/sidekiq_cron.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../cron'
+
+module Wurk
+  module Import
+    # Reads the schedule sidekiq-cron keeps in Redis and maps each entry onto a
+    # native periodic loop (`Wurk::Cron::Loop`). `rake wurk:import:cron` drives
+    # it: a dry run prints the plan plus a `config.periodic` block to paste into
+    # code; `APPLY=1` persists the loops straight into the `periodic` registry.
+    #
+    # sidekiq-cron's layout (v1.12+ / 2.x, namespaced): `cron_jobs:<namespace>`
+    # is a SET of `cron_job:<namespace>:<name>` HASH keys. Releases before
+    # namespaces used one `cron_jobs` SET of `cron_job:<name>` keys; both are
+    # read. Nothing here writes or deletes a sidekiq-cron key, so a rollback to
+    # Sidekiq still finds its schedule intact.
+    class SidekiqCron
+      LEGACY_SET = 'cron_jobs'
+      NAMESPACED_SETS = 'cron_jobs:*'
+      GLOBALID_KEY = '_sc_globalid'
+      TRUE_FLAG = /\A(?:true|t|yes|y|1)\z/i
+      ZONE_TOKEN = %r{\A[A-Za-z][A-Za-z0-9_+\-/]*\z}
+
+      # One sidekiq-cron entry and what it becomes. `loop` is nil exactly when
+      # `skip_reason` says why the entry cannot be carried over unchanged.
+      Entry = Struct.new(:key, :namespace, :name, :source, :loop, :skip_reason, :warnings, keyword_init: true) do
+        def importable? = !loop.nil?
+      end
+
+      def entries
+        rows = redis do |c|
+          keys = schedule_keys(c)
+          keys.map { |key| [key, c.call('HGETALL', key).to_h] }
+        end
+        rows.reject { |(_key, h)| h.empty? }.map { |key, h| build_entry(key, h) }
+      end
+
+      # Persists every importable entry and returns the entries it wrote.
+      # Idempotent: a loop's lid is a hash of its schedule, class and options,
+      # so a second run rewrites the same keys, and `paused` is only seeded
+      # (Cron.persist uses HSETNX), so a dashboard pause survives a re-import.
+      def apply!(list = entries)
+        list.select(&:importable?).each { |entry| Cron.persist(entry.loop) }
+      end
+
+      def registered?(lid)
+        redis { |c| c.call('SISMEMBER', Cron::PERIODIC_KEY, lid) }.to_i == 1
+      end
+
+      # What `rake wurk:import:cron` prints. Returns the entries it found.
+      def run(apply:, out: $stdout)
+        list = entries
+        if list.empty?
+          out.puts "No sidekiq-cron entries found (looked for #{NAMESPACED_SETS} and #{LEGACY_SET})."
+          return list
+        end
+
+        report(list, out)
+        if apply
+          written = apply!(list)
+          out.puts "\nRegistered #{written.size} loop(s) in the `#{Cron::PERIODIC_KEY}` registry. " \
+                   'sidekiq-cron keys were left untouched.'
+        else
+          out.puts "\nDry run: nothing was written. Re-run with APPLY=1 to register the importable loops in Redis."
+        end
+        list
+      end
+
+      private
+
+      def report(list, out)
+        importable = list.select(&:importable?)
+        out.puts "sidekiq-cron entries: #{list.size} (#{importable.size} importable, " \
+                 "#{list.size - importable.size} skipped)\n\n"
+        list.each { |entry| report_entry(entry, out) }
+        return if importable.empty?
+
+        out.puts "\nTo keep these in code (recommended), paste into config/initializers/wurk.rb:\n\n"
+        out.puts snippet(importable)
+      end
+
+      def report_entry(entry, out)
+        id = "#{entry.namespace}/#{entry.name}"
+        if entry.importable?
+          lp = entry.loop
+          state = registered?(lp.lid) ? 'already registered' : 'new'
+          out.puts "  import  #{id}  #{lp.schedule.inspect} #{lp.klass}  -> lid #{lp.lid} (#{state})"
+        else
+          out.puts "  skip    #{id}  #{entry.skip_reason}"
+        end
+        entry.warnings.each { |w| out.puts "  warn    #{id}  #{w}" }
+      end
+
+      def snippet(entries)
+        lines = entries.map do |entry|
+          lp = entry.loop
+          opts = lp.options.map { |k, v| "#{k}: #{v.inspect}" }
+          opts << "tz: #{lp.tz_name.inspect}" if lp.tz_name
+          "    mgr.register(#{[lp.schedule.inspect, lp.klass.inspect, *opts].join(', ')})"
+        end
+        ['Wurk.configure_server do |config|', '  config.periodic do |mgr|', *lines, '  end', 'end'].join("\n")
+      end
+
+      def schedule_keys(conn)
+        sets = scan(conn, NAMESPACED_SETS)
+        sets << LEGACY_SET if conn.call('EXISTS', LEGACY_SET).to_i == 1
+        sets.flat_map { |set| conn.call('SMEMBERS', set) }.uniq.sort
+      end
+
+      def scan(conn, pattern)
+        cursor = '0'
+        found = []
+        loop do
+          cursor, batch = conn.call('SCAN', cursor, 'MATCH', pattern, 'COUNT', 500)
+          found.concat(batch)
+          break if cursor == '0'
+        end
+        found.select { |key| conn.call('TYPE', key) == 'set' }.sort
+      end
+
+      def build_entry(key, h)
+        entry = Entry.new(key: key, namespace: blank(h['namespace']) || 'default', name: h['name'].to_s,
+                          source: blank(h['source']) || 'dynamic', warnings: [])
+        entry.skip_reason = skip_reason(h)
+        entry.loop = build_loop(h, entry) unless entry.skip_reason
+        entry
+      rescue ArgumentError => e
+        entry.loop = nil
+        entry.skip_reason = e.message
+        entry
+      end
+
+      def skip_reason(hash)
+        return 'no class (`klass`) recorded' if blank(hash['klass'] || hash['class']).nil?
+        return 'no cron expression recorded' if blank(hash['cron']).nil?
+        return '`date_as_argument` appends the enqueue time to args; Wurk loops have no equivalent' if
+          flag?(hash['date_as_argument'])
+        return 'args carry a serialized GlobalID; Wurk loops pass args verbatim' if
+          hash['args'].to_s.include?(GLOBALID_KEY)
+
+        nil
+      end
+
+      def build_loop(hash, entry)
+        schedule, tz = split_zone(hash['cron'].strip)
+        validate_schedule!(schedule)
+        message = parse_json(hash['message'])
+        Cron::Loop.new(schedule: schedule, klass: (hash['klass'] || hash['class']).to_s, tz: tz,
+                       options: options_for(hash, message, entry))
+      end
+
+      def validate_schedule!(schedule)
+        Cron::Parser.new(schedule)
+      rescue ArgumentError => e
+        raise ArgumentError, "unsupported schedule #{schedule.inspect} (#{e.message}); Wurk takes a " \
+                             '5-field crontab or an @alias, not fugit seconds or natural language'
+      end
+
+      # fugit accepts a trailing zone (`0 5 * * * Europe/Paris`); Wurk takes the
+      # zone as `tz:`. A sixth token that is not a zone is fugit's seconds field
+      # or natural language, which the native 5-field parser rejects.
+      def split_zone(cron)
+        tokens = cron.split
+        return [cron, nil] unless tokens.size == 6 && tokens.last.match?(ZONE_TOKEN) && tokens.last.match?(/[A-Za-z]/)
+
+        zone = tokens.last
+        raise ArgumentError, "unknown timezone #{zone.inspect}" unless Cron::Parser.resolve_zone(zone)
+
+        [tokens.first(5).join(' '), zone]
+      end
+
+      def options_for(hash, message, entry)
+        add_warnings(hash, entry)
+        args = args_for(hash['args'])
+        opts = { 'label' => label_for(entry) }
+        opts['args'] = args unless args.empty?
+        opts.merge!(message_options(message))
+        opts['paused'] = true if hash['status'] == 'disabled'
+        opts
+      end
+
+      # The label is part of the loop's lid, so it has to carry the namespace:
+      # sidekiq-cron keys an entry by namespace + name, and `nightly` in
+      # `billing` and in `default` are two jobs that must stay two loops. The
+      # default namespace (and the pre-namespace legacy set) keeps the bare
+      # name, so an entry imported before this keeps its lid on re-import.
+      def label_for(entry)
+        entry.namespace == 'default' ? entry.name : "#{entry.namespace}/#{entry.name}"
+      end
+
+      # sidekiq-cron pushes the queue and retry frozen into `message` when the
+      # entry was saved, not the worker's current options.
+      def message_options(message)
+        opts = {}
+        opts['queue'] = message['queue'] if blank(message['queue'])
+        opts['retry'] = retry_value(message['retry']) unless message['retry'].nil?
+        opts
+      end
+
+      def add_warnings(hash, entry)
+        if blank(hash['queue_name_prefix'])
+          entry.warnings << "ActiveJob `queue_name_prefix` #{hash['queue_name_prefix'].inspect} is not carried over"
+        end
+        return unless flag?(hash['symbolize_args'])
+
+        entry.warnings << '`symbolize_args` is not carried over; hash args arrive with string keys'
+      end
+
+      # sidekiq-cron stores args as a JSON string, falling back to `[*raw]` when
+      # it does not parse; a bare Hash becomes the single argument.
+      def args_for(raw)
+        return [] if blank(raw).nil?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Array) ? parsed : [parsed]
+      rescue JSON::ParserError
+        [raw]
+      end
+
+      def retry_value(value)
+        return value unless value.is_a?(String)
+        return true if value == 'true'
+        return false if value == 'false'
+
+        value.match?(/\A\d+\z/) ? value.to_i : value
+      end
+
+      def parse_json(raw)
+        return {} if blank(raw).nil?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def flag?(value) = value == true || value.to_s.match?(TRUE_FLAG)
+
+      def blank(value)
+        str = value&.to_s
+        str.nil? || str.strip.empty? ? nil : str
+      end
+
+      def redis(&) = Wurk.redis(&)
+    end
+  end
+end

data/lib/wurk/job/options.rb

@@ -20,15 +20,34 @@ module Wurk
         base.extend(ClassMethods)
       end
 
+      # Also the options half of {Wurk::Worker::ClassMethods}, so an ActiveJob
+      # class configuring a Wurk option is told about a bad value at the same
+      # place a plain worker is.
       module ClassMethods
-        # Deliberately identical to Wurk::Worker::ClassMethods#sidekiq_options,
-        # validation included: an ActiveJob class configuring a Wurk option
-        # must be told about a bad value at the same place a plain worker is.
+        # Set per-class job options (merged over any inherited options).
+        #
+        # @example
+        #   sidekiq_options queue: "mailers", retry: 3, unique_for: 10.minutes
+        # @example Opt into Wurk::Status tracking
+        #   sidekiq_options track: true
+        # @example Bound one attempt, and the job as a whole
+        #   sidekiq_options timeout: 30, deadline: 5.minutes
+        # @example Collapse a burst of enqueues into one job
+        #   sidekiq_options collapse: { policy: :debounce, wait: 5, max_wait: 60 }
+        # @param opts [Hash] any of `queue:`, `retry:`, `dead:`, `backtrace:`,
+        #   `expires_in:`, `tags:`, `pool:`, `unique_for:`, `track:`, `timeout:`,
+        #   `deadline:`, `collapse:`, … (see the migration guide's sidekiq_options
+        #   table for the full set)
+        # @return [Hash] the merged, string-keyed options hash
         def sidekiq_options(opts = {})
           stringified = opts.transform_keys(&:to_s)
           Wurk::JobUtil.validate_track!(stringified['track'], stringified) if stringified.key?('track')
           Wurk::JobUtil.validate_bounds!(stringified)
           merged = get_sidekiq_options.merge(stringified)
+          # On the merged options rather than the new ones, and before the
+          # assign: a subclass adding `collapse:` to a parent's `unique_for:`
+          # has declared both, and only the merge can see it. Raising first
+          # leaves the class holding the options it had.
           Wurk::Collapse.policy_for(merged)
           @sidekiq_options_hash = merged
         end

data/lib/wurk/job_logger.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'redact'
+
 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:
+  # Two entry points, called from Processor#dispatch 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
@@ -24,7 +26,14 @@ module Wurk
       # #context_hash runs it per job only to walk a list that cannot change
       # after boot (Configuration freezes at launch).
       @logged_attributes = Array(@config[:logged_job_attributes]).map { |attr| [attr, attr.to_sym] }.freeze
-      @skip = !!@config[:skip_default_job_logging]
+      # A host logger need not be a ::Logger >= 1.6 (SemanticLogger, a
+      # broadcast wrapper): without #with_level a per-job `log_level` is
+      # ignored rather than failing the job it was meant to annotate.
+      @with_level = @logger.respond_to?(:with_level)
+      @skip = @config[:skip_default_job_logging] ? true : false
+      # Only consulted when `args` is a logged attribute — the one place this
+      # logger prints arguments. See Wurk::Redact.
+      @redact = @logged_attributes.any? { |attr, _| attr == 'args' } ? @config[:redact_args] : nil
     end
 
     def call(_item, _queue)
@@ -49,7 +58,7 @@ module Wurk
 
       level = job_hash['log_level']
       Wurk::Context.with(h) do
-        if level
+        if level && @with_level
           @logger.with_level(level, &block)
         else
           yield
@@ -75,6 +84,7 @@ module Wurk
       @logged_attributes.each do |attr, sym|
         h[sym] = job_hash[attr] if job_hash.key?(attr)
       end
+      h[:args] = Redact.args(job_hash, @redact) if @redact && job_hash.key?('args')
       h
     end
   end

data/lib/wurk/job_record.rb

@@ -2,6 +2,7 @@
 
 require 'base64'
 require 'zlib'
+require_relative 'redact'
 
 module Wurk
   # One job payload viewed from the data API (Queue#each / JobSet#each).
@@ -22,8 +23,8 @@ module Wurk
       ActionMailer::Parameterized::DeliveryJob
       ActionMailer::MailDeliveryJob
     ].freeze
-
-    attr_reader :queue
+    AJ_PREFIX = '_aj_'
+    AJ_GLOBALID = '_aj_globalid'
 
     # @param item [String, Hash] raw JSON payload or pre-parsed hash.
     # @param queue_name [String, nil] queue this record came from.
@@ -35,12 +36,21 @@ module Wurk
         @item = item
         @value = nil
       end
-      @queue = queue_name || (@item && @item['queue'])
+      @queue = queue_name
     end
 
-    # Lazily parsed payload. Memoized; never re-parses.
+    def queue = @queue || item['queue']
+
+    # Lazily parsed payload. Memoized; never re-parses. Invalid JSON reads as
+    # an empty hash whose raw bytes become `args`, as upstream does, so one
+    # corrupt payload can't break a dashboard page or a Queue#each walk.
     def item
-      @item ||= Wurk.load_json(@value)
+      @item ||= begin
+        Wurk.load_json(@value)
+      rescue ::JSON::ParserError
+        @invalid_args = [@value]
+        {}
+      end
     end
 
     # Lazily serialized payload. When constructed from a Hash, we
@@ -50,10 +60,14 @@ module Wurk
     end
 
     def klass         = item['class']
-    def args          = item['args']
     def jid           = item['jid']
     def bid           = item['bid']
 
+    def args
+      parsed = item
+      @invalid_args || parsed['args']
+    end
+
     # IterableJob progress for this job, or nil for a non-iterable job (no
     # `it-<jid>` HASH). Spec §19.3. Reads via the IterableJobQuery data API.
     def iterable_state
@@ -64,7 +78,9 @@ module Wurk
 
     def tags          = item['tags'] || []
     def enqueued_at   = parse_time(item['enqueued_at'])
-    def created_at    = parse_time(item['created_at'])
+    # Falls back to enqueued_at as upstream does; nil (not upstream's epoch 0)
+    # only when both are absent, so a dashboard shows "unknown", not 1970.
+    def created_at    = parse_time(item['created_at'] || item['enqueued_at'])
     def failed_at     = parse_time(item['failed_at'])
     def retried_at    = parse_time(item['retried_at'])
 
@@ -86,13 +102,13 @@ module Wurk
     # current integer-ms `enqueued_at` shapes. Returns 0.0 when missing
     # or somehow in the future (clock skew).
     def latency
-      JobRecord.latency_from(item['enqueued_at'])
+      JobRecord.latency_from(item['enqueued_at'] || item['created_at'])
     end
 
     # Removes exactly this payload's bytes from the queue list. Returns
     # true when LREM removed ≥1 entry. Idempotent. Method name is
     # Sidekiq wire-compat — renaming would break `JobRecord#delete`.
-    def delete # rubocop:disable Naming/PredicateMethod
+    def delete
       removed = Wurk.redis { |c| c.call('LREM', Keys.queue(@queue), 1, value) }
       removed.to_i.positive?
     end
@@ -102,17 +118,25 @@ module Wurk
     def display_class
       return @display_class if defined?(@display_class)
 
-      @display_class = active_job_wrapper? ? unwrap_class : klass
+      @display_class = item['display_class'] || (active_job_wrapper? ? unwrap_class : klass)
     end
 
     # UI-facing args. Encrypted jobs (§4.7) get their envelope last arg
-    # masked as "<encrypted>" so ciphertext never reaches the dashboard;
+    # masked as "[encrypted data]" so ciphertext never reaches the dashboard;
     # redaction keys off the envelope shape, so it fires whether or not the
     # stored hash carried the `encrypt` flag. Cleartext preceding args stay
     # visible for triage. Display-only — the stored payload is untouched.
+    #
+    # A host `redact_args` hook (Wurk::Redact) replaces all of that: it sees
+    # the whole job and decides what is shown. This is the single choke point
+    # for every surface that renders a job — dashboard JSON, search, the /v1
+    # machine API, Sidekiq::Web-style views.
     def display_args
       return @display_args if defined?(@display_args)
 
+      hook = Wurk::Redact.hook
+      return @display_args = Wurk::Redact.args(item, hook) if hook
+
       base = active_job_wrapper? ? unwrap_args : args
       @display_args = Wurk::Encryption.redact_args('args' => base, 'encrypt' => item['encrypt'])
     end
@@ -151,21 +175,46 @@ module Wurk
       "#{mailer_args[0]}##{mailer_args[1]}"
     end
 
+    # ActiveJob serializes GlobalID args as {"_aj_globalid" => gid} and tags
+    # hashes with `_aj_*` bookkeeping keys; upstream shows the gid string and
+    # drops the bookkeeping. ActionMailer payloads lead with
+    # [mailer, method, "deliver_now"]; MailDeliveryJob's real args are the
+    # trailing {"params", "args"} hash.
     def unwrap_args
-      job_args = args.dig(0, 'arguments') || []
-      wrapped = item['wrapped']
-      return job_args unless ACTION_MAILER_JOBS.include?(wrapped)
+      job_args = deserialize_aj(args.dig(0, 'arguments') || [])
+      case item['wrapped']
+      when *ACTION_MAILER_JOBS then mailer_args(item['wrapped'], job_args.drop(3))
+      else job_args
+      end
+    end
+
+    def mailer_args(wrapped, rest)
+      return rest unless wrapped == 'ActionMailer::MailDeliveryJob' && rest.first.is_a?(Hash)
+
+      rest.first.values_at('params', 'args')
+    end
+
+    def deserialize_aj(arg)
+      case arg
+      when Array then arg.map { |a| deserialize_aj(a) }
+      when Hash
+        return arg[AJ_GLOBALID] if arg.size == 1 && arg.key?(AJ_GLOBALID)
 
-      # ActionMailer payloads start with [mailer, method, "deliver_now", *real_args]
-      job_args.drop(3)
+        arg.reject { |k, _| k.start_with?(AJ_PREFIX) }.transform_values { |v| deserialize_aj(v) }
+      else arg
+      end
     end
 
-    # Parse Sidekiq's mixed time formats (Float secs, Integer ms) into Time.
+    # Parse Sidekiq's mixed time formats (Float secs, Integer ms) into a UTC
+    # Time, whatever the branch, so callers never see the host's zone.
+    # Integer ms is split into whole seconds + ms rather than divided as a
+    # Float, which would round some timestamps a millisecond off.
     def parse_time(value)
       return nil if value.nil?
+      return ::Time.at(value).utc if value < 10_000_000_000
+      return ::Time.at(value / 1_000.0).utc unless value.is_a?(Integer)
 
-      ms = value < 10_000_000_000 ? value * 1_000 : value
-      ::Time.at(ms / 1_000.0)
+      ::Time.at(value / 1_000, value % 1_000, :millisecond).utc
     end
   end
 end

data/lib/wurk/job_retry.rb

@@ -208,7 +208,9 @@ module Wurk
     # Caller branches on strategy; seconds is meaningful only for :default.
     def delay_for(jobinst, count, exception, msg)
       rv = run_retry_in_block(jobinst, count, exception, msg)
-      rv = rv.to_i if rv.is_a?(::Float)
+      # `10.minutes * count` (a Duration), `"60"` and `30.0` all mean seconds;
+      # Symbols have no #to_i, so `:kill` / `:discard` pass through intact.
+      rv = rv.to_i if rv.respond_to?(:to_i)
       default_delay = (count**4) + 15
 
       case rv
@@ -224,8 +226,7 @@ module Wurk
     end
 
     def run_retry_in_block(jobinst, count, exception, msg)
-      block = jobinst&.class&.sidekiq_retry_in_block
-      block = wrapped_block(msg, :sidekiq_retry_in_block) || block if msg['wrapped']
+      block = msg['wrapped'] ? wrapped_block(msg, :sidekiq_retry_in_block) : jobinst&.class&.sidekiq_retry_in_block
       block&.call(count, exception, msg)
     rescue ::Exception => e # rubocop:disable Lint/RescueException
       handle_exception(e, context: "Failure scheduling retry via `sidekiq_retry_in` on #{jobinst&.class&.name}")
@@ -249,8 +250,11 @@ module Wurk
     end
 
     def run_exhausted_block(jobinst, msg, exception)
-      block = jobinst&.class&.sidekiq_retries_exhausted_block
-      block = wrapped_block(msg, :sidekiq_retries_exhausted_block) || block if msg['wrapped']
+      block = if msg['wrapped']
+                wrapped_block(msg, :sidekiq_retries_exhausted_block)
+              else
+                jobinst&.class&.sidekiq_retries_exhausted_block
+              end
       block&.call(msg, exception)
     rescue ::Exception => e # rubocop:disable Lint/RescueException
       handle_exception(e, context: 'Error calling retries_exhausted', job: msg)
@@ -258,7 +262,9 @@ module Wurk
     end
 
     # Wrappers (ActiveJob, custom) expose retry blocks on the wrapped class
-    # via `msg["wrapped"]`. We look up the constant and prefer its block.
+    # via `msg["wrapped"]`. A wrapped job uses the wrapped class's block or
+    # none — never the wrapper's (Sidekiq's rule): the wrapper is shared by
+    # every wrapped class, so its block would apply to all of them.
     def wrapped_block(msg, attr)
       wrapped = ::Object.const_get(msg['wrapped'])
       wrapped.respond_to?(attr) ? wrapped.public_send(attr) : nil