jobpayload 0.1.0

data/lib/jobpayload/canonical.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JobPayload
+  # Helpers for JSON-compatible data: deterministic serialization and deep copies.
+  module Canonical
+    module_function
+
+    # Returns a copy of +value+ with every Hash's keys sorted (recursively), so
+    # output never depends on Hash insertion order.
+    def sort_keys(value)
+      case value
+      when Hash
+        value.keys.sort_by(&:to_s).each_with_object({}) { |key, sorted| sorted[key] = sort_keys(value[key]) }
+      when Array
+        value.map { |element| sort_keys(element) }
+      else
+        value
+      end
+    end
+
+    # Pretty printed, key-sorted, UTF-8 JSON with LF newlines and a final newline.
+    def generate(value)
+      pretty(sort_keys(value))
+    end
+
+    # Pretty prints JSON-compatible data with two-space indentation, keeping
+    # Hash key order as given. The layout is produced here rather than by
+    # JSON.pretty_generate so the bytes do not depend on the json gem version
+    # (for example, older versions render an empty object as "{\n}").
+    def pretty(value)
+      "#{dump(value, 0)}\n".encode(Encoding::UTF_8)
+    end
+
+    def dump(value, depth)
+      indent = "  " * (depth + 1)
+      closing = "  " * depth
+      case value
+      when Hash
+        return "{}" if value.empty?
+
+        members = value.map { |key, element| "#{indent}#{::JSON.generate(key.to_s)}: #{dump(element, depth + 1)}" }
+        "{\n#{members.join(",\n")}\n#{closing}}"
+      when Array
+        return "[]" if value.empty?
+
+        "[\n#{value.map { |element| "#{indent}#{dump(element, depth + 1)}" }.join(",\n")}\n#{closing}]"
+      when String, Integer, Float, true, false, nil
+        ::JSON.generate(value)
+      else
+        raise ArgumentError, "not a JSON-compatible value: #{value.class}"
+      end
+    end
+
+    # Recursive copy of a parsed JSON structure (Hash/Array/String/scalars).
+    # Each check phase gets its own copy so a deserializer that mutates its
+    # input cannot influence another phase.
+    def deep_copy(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, element), copy| copy[deep_copy(key)] = deep_copy(element) }
+      when Array
+        value.map { |element| deep_copy(element) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+
+    # Writes +content+ to +path+ atomically (temporary file in the same
+    # directory, then rename).
+    def atomic_write(path, content)
+      dir = File.dirname(path)
+      temp = File.join(dir, ".#{File.basename(path)}.#{Process.pid}.#{rand(1 << 32)}.tmp")
+      File.open(temp, "wb") do |file|
+        file.write(content)
+        file.flush
+        file.fsync
+      end
+      File.rename(temp, path)
+    ensure
+      File.unlink(temp) if temp && File.exist?(temp)
+    end
+  end
+end

data/lib/jobpayload/case_registry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # Collects the fixture definitions declared by a cases file.
+  #
+  # A registry is only "current" while CaseRegistry.load is evaluating a cases
+  # file, so JobPayload.define never writes into process-wide state.
+  class CaseRegistry
+    Case = Struct.new(:name, :block, :location)
+
+    # Thread-local key holding the registry being populated.
+    CURRENT_KEY = :__jobpayload_case_registry
+
+    def self.current
+      Thread.current[CURRENT_KEY] or
+        raise ConfigurationError, "JobPayload.define can only be called from a cases file loaded by `jobpayload snapshot`"
+    end
+
+    # Loads the cases file at +path+ and returns the populated registry.
+    def self.load(path)
+      raise ConfigurationError, "cases file not found: #{path}" unless File.file?(path)
+
+      registry = new
+      previous = Thread.current[CURRENT_KEY]
+      Thread.current[CURRENT_KEY] = registry
+      begin
+        Kernel.load(File.expand_path(path))
+      rescue ConfigurationError
+        raise
+      rescue StandardError, ScriptError => e
+        raise ConfigurationError, "failed to load cases file #{path}: #{e.class}: #{e.message}"
+      ensure
+        Thread.current[CURRENT_KEY] = previous
+      end
+      raise ConfigurationError, "no fixtures defined in #{path}" if registry.cases.empty?
+
+      registry
+    end
+
+    def initialize
+      @cases = {}
+    end
+
+    # Fixtures sorted by name, independent of declaration order.
+    def cases
+      @cases.values.sort_by(&:name)
+    end
+
+    def define(&block)
+      raise ConfigurationError, "JobPayload.define requires a block" unless block
+
+      DSL.new(self).instance_eval(&block)
+      self
+    end
+
+    def add(name, location, &block)
+      unless JobPayload.valid_name?(name)
+        raise ConfigurationError,
+          "invalid fixture name #{name.inspect} (#{location}); names must match #{NAME_PATTERN.source}"
+      end
+      raise ConfigurationError, "fixture #{name.inspect} has no block (#{location})" unless block
+      # Names differing only in case would map to the same file on
+      # case-insensitive file systems (macOS, Windows), so they are duplicates too.
+      if (existing = @cases.values.find { |kase| kase.name.casecmp?(name) })
+        raise ConfigurationError,
+          "duplicate fixture name #{name.inspect} (#{location}; #{existing.name.inspect} first defined at #{existing.location}; " \
+          "names must be unique ignoring case)"
+      end
+
+      @cases[name] = Case.new(name, block, location)
+    end
+
+    # Evaluation context for JobPayload.define blocks.
+    class DSL
+      def initialize(registry)
+        @registry = registry
+      end
+
+      def fixture(name, &block)
+        caller_location = caller_locations(1, 1).first
+        @registry.add(name, "#{caller_location.path}:#{caller_location.lineno}", &block)
+        nil
+      end
+    end
+  end
+end

data/lib/jobpayload/checker.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JobPayload
+  # Checks that previously serialized job payloads can be deserialized by the
+  # currently loaded application.
+  #
+  # For each fixture, in order:
+  #   A. the fixture wrapper must be valid (done by Fixture.parse)
+  #   B. ActiveJob::Base.deserialize(job_data) must succeed
+  #   C. ActiveJob::Arguments.deserialize(job_data["arguments"]) must succeed
+  #
+  # Each phase receives its own deep copy of the payload. The job is never
+  # performed, enqueued or retried.
+  class Checker
+    MESSAGES = {
+      "AJP101" => "Job class cannot be resolved by the current application.",
+      "AJP102" => "Job class exists but its deserialize(job_data) cannot restore the old payload.",
+      "AJP201" => "Old payload cannot be deserialized by the current application.",
+      "AJP202" => "GlobalID target record was not found in the current test environment.",
+      "AJP900" => "The check environment failed before compatibility could be determined."
+    }.freeze
+
+    RESCUED = [StandardError, ScriptError, SystemStackError].freeze
+
+    # Phase C codes from least to most severe.
+    ARGUMENT_CODE_RANK = { "AJP202" => 0, "AJP201" => 1, "AJP900" => 2 }.freeze
+
+    def call(fixtures)
+      fixture_results = fixtures.map { |fixture| check(fixture) }
+      fixture_results.sort_by! { |result| [result.name, result.path.to_s] }
+      Result.new(fixture_results)
+    end
+
+    def check(fixture)
+      if fixture.is_a?(Fixture::Invalid)
+        finding = Finding.build(code: "AJP001", fixture: fixture.name,
+          message: "Fixture is invalid: #{fixture.reason}.")
+        return Result::FixtureResult.new(fixture.name, fixture.path, [finding])
+      end
+
+      findings = []
+      findings.concat(check_job(fixture))
+      findings.concat(check_arguments(fixture))
+      Result::FixtureResult.new(fixture.name, fixture.path, findings)
+    end
+
+    private
+
+    # Phase B.
+    def check_job(fixture)
+      class_name = fixture.job_class
+      begin
+        klass = ::ActiveSupport::Inflector.safe_constantize(class_name)
+      rescue *RESCUED => e
+        return [finding("AJP101", fixture, exception: e)] unless environment?(e)
+
+        return [finding("AJP900", fixture, exception: e)]
+      end
+      unless klass.is_a?(Class) && klass <= ::ActiveJob::Base
+        detail = klass ? "#{class_name} is not an ActiveJob::Base subclass" : "uninitialized constant #{class_name}"
+        return [finding("AJP101", fixture, message: "#{MESSAGES.fetch('AJP101')} (#{detail})")]
+      end
+
+      ::ActiveJob::Base.deserialize(Canonical.deep_copy(fixture.job))
+      []
+    rescue *RESCUED => e
+      [finding(environment?(e) ? "AJP900" : "AJP102", fixture, exception: e)]
+    end
+
+    # Phase C. The full deserialize call is the source of truth for whether
+    # the arguments are readable. When it fails, each argument is retried on
+    # its own to point at every failing argument: Active Job stops at the first
+    # error, so a missing GlobalID record (inconclusive) in arguments[0] must
+    # not hide a broken serializer in arguments[1].
+    def check_arguments(fixture)
+      # Kept out of a rescue clause on purpose: exceptions raised while `$!` is
+      # set get it as their cause, which would leak the first failure into the
+      # cause chain (and classification) of every per-argument retry.
+      e = ArgumentLocator.deserialize_error(fixture.job["arguments"], wrap: false)
+      return [] unless e
+
+      findings = ArgumentLocator.call(fixture.job["arguments"]).map do |path, error, leaf|
+        finding(argument_code(error, leaf), fixture, exception: error, argument_path: path)
+      end
+      # Never report less than the full call did (for example when no single
+      # argument fails on its own). The full call has no single failing leaf:
+      # a record-missing error there is already explained by any per-argument
+      # finding, and is reported as breaking when there is none.
+      overall = argument_code(e, nil)
+      floor = ExceptionClassifier.call(e) == :record_missing ? 0 : ARGUMENT_CODE_RANK.fetch(overall)
+      unless findings.any? { |f| ARGUMENT_CODE_RANK.fetch(f.code) >= floor }
+        findings << finding(overall, fixture, exception: e, argument_path: "arguments")
+      end
+      findings
+    end
+
+    # AJP202 (inconclusive) only when the failing serialized leaf is an Active
+    # Job GlobalID reference and a record-missing error is in the cause chain.
+    # A custom serializer that raises RecordNotFound (for example a lookup by a
+    # renamed key) is a broken payload: AJP201.
+    def argument_code(exception, leaf)
+      case ExceptionClassifier.call(exception)
+      when :environment then "AJP900"
+      when :record_missing then ArgumentLocator.global_id?(leaf) ? "AJP202" : "AJP201"
+      else "AJP201"
+      end
+    end
+
+    def environment?(exception)
+      ExceptionClassifier.call(exception) == :environment
+    end
+
+    def finding(code, fixture, exception: nil, argument_path: nil, message: MESSAGES.fetch(code))
+      Finding.build(code: code, fixture: fixture.name, job_class: fixture.job_class,
+        argument_path: argument_path, message: message, exception: exception)
+    end
+
+    # Finds every failing argument. Inside plain arrays and hashes it descends
+    # to the nested values that fail on their own. Returns
+    # [[path, exception, failing_value]].
+    module ArgumentLocator
+      # Keys Active Job adds to a serialized plain hash. Any other key,
+      # including user keys such as "_aj_custom", holds a serialized value.
+      HASH_METADATA_KEYS = %w[_aj_symbol_keys _aj_ruby2_keywords _aj_hash_with_indifferent_access].freeze
+
+      module_function
+
+      def call(arguments)
+        arguments.each_with_index.flat_map { |argument, index| failures(argument, "arguments[#{index}]") }
+      end
+
+      def failures(value, path)
+        error = deserialize_error(value)
+        return [] unless error
+
+        failing = []
+        nested = children(value, path).flat_map do |child, child_path, key|
+          child_failures = failures(child, child_path)
+          failing << key unless child_failures.empty?
+          child_failures
+        end
+        return [[path, error, value]] if nested.empty?
+
+        # The container can also be broken on its own (for example malformed
+        # "_aj_" metadata). Retry it with the failing children blanked out so
+        # that a missing GlobalID inside cannot hide that.
+        own_error = deserialize_error(without(value, failing))
+        own_error ? nested << [path, own_error, value] : nested
+      end
+
+      def without(value, keys)
+        copy = Canonical.deep_copy(value)
+        keys.each { |key| copy[key] = nil }
+        copy
+      end
+
+      # Same test Active Job uses for a serialized GlobalID: a one-key hash.
+      def global_id?(value)
+        value.is_a?(Hash) && value.size == 1 && value["_aj_globalid"].is_a?(String)
+      end
+
+      def children(value, path)
+        case value
+        when Array
+          value.each_with_index.map { |child, index| [child, "#{path}[#{index}]", index] }
+        when Hash
+          return [] if value.key?("_aj_serialized") || value.key?("_aj_globalid")
+
+          value.reject { |key, _| HASH_METADATA_KEYS.include?(key) }.map { |key, child| [child, "#{path}[#{JSON.generate(key)}]", key] }
+        else
+          []
+        end
+      end
+
+      # Deserializes +value+ as a single argument (or, with wrap: false, as the
+      # full argument list) and returns the exception raised, if any.
+      def deserialize_error(value, wrap: true)
+        ::ActiveJob::Arguments.deserialize(Canonical.deep_copy(wrap ? [value] : value))
+        nil
+      rescue *RESCUED => e
+        e
+      end
+    end
+  end
+end

data/lib/jobpayload/cli.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module JobPayload
+  # Command line interface.
+  #
+  # Order of operations is fixed: parse options, boot the host application
+  # (once), then use Active Job APIs. Results go to stdout; usage, configuration
+  # and boot errors go to stderr.
+  class CLI
+    EXIT_SUCCESS = 0
+    EXIT_FAILURE = 1
+    EXIT_ERROR = 2
+
+    DEFAULT_CASES = "test/jobpayload_cases.rb"
+    DEFAULT_FIXTURES = "test/jobpayload_fixtures"
+
+    USAGE = <<~TEXT
+      Usage: jobpayload COMMAND [options]
+
+      Commands:
+        snapshot    Write baseline fixtures from snapshot cases (ActiveJob::Base#serialize)
+        check       Check that fixtures can be deserialized by the current application
+
+      Options:
+        -v, --version   Print the version
+        -h, --help      Print this help
+
+      Run `jobpayload COMMAND --help` for command options.
+    TEXT
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      # An argument that is not valid in its encoding (for example a path
+      # with non-UTF-8 bytes under a UTF-8 locale) makes OptionParser's regexp
+      # matching raise. Keep its exact bytes as a binary string, which is safe
+      # for option parsing and file system calls; only output is scrubbed.
+      @argv = argv.map { |arg| arg.valid_encoding? ? arg.dup : arg.b }
+      @stdout = stdout
+      @stderr = stderr
+      @debug = false
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when "snapshot" then with_stdout_redirected { snapshot }
+      when "check" then with_stdout_redirected { check }
+      when "-v", "--version", "version"
+        @stdout.puts("jobpayload v#{VERSION}")
+        EXIT_SUCCESS
+      when "-h", "--help", "help"
+        @stdout.print(USAGE)
+        EXIT_SUCCESS
+      when nil
+        usage_error("no command given")
+      else
+        usage_error("unknown command #{command.inspect}")
+      end
+    rescue OptionParser::ParseError => e
+      usage_error(e.message)
+    rescue SystemExit => e
+      # Application code (boot file, initializers, serializers, case blocks)
+      # called exit/abort. Never let its status masquerade as exit 0 or 1.
+      error(Error.new("the application exited with status #{e.status} while jobpayload was running"))
+    rescue Error => e
+      error(e)
+    rescue Interrupt, SignalException
+      raise
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      # Anything else (SystemStackError from pathologically deep fixtures, or
+      # an application exception that does not inherit from StandardError)
+      # is a tool error: exit 2, never the compatibility-failure status 1.
+      error(e, prefix: "internal error: #{e.class}: ")
+    end
+
+    private
+
+    # The host application (boot file, initializers, serializers, case blocks)
+    # may print with puts/print. Send that to stderr so stdout only carries
+    # jobpayload's own result (which is written to @stdout directly).
+    def with_stdout_redirected
+      saved = $stdout
+      $stdout = @stderr
+      yield
+    ensure
+      $stdout = saved
+    end
+
+    def snapshot
+      options = {
+        cases: DEFAULT_CASES, output: DEFAULT_FIXTURES, boot: Boot::DEFAULT_PATH,
+        environment: Boot::DEFAULT_ENVIRONMENT, update: false, format: "text"
+      }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: jobpayload snapshot [options]"
+        opts.on("--cases PATH", "Snapshot cases file (default: #{DEFAULT_CASES})") { |v| options[:cases] = v }
+        opts.on("--output DIR", "Fixture output directory (default: #{DEFAULT_FIXTURES})") { |v| options[:output] = v }
+        boot_options(opts, options)
+        opts.on("--update", "Replace existing fixtures whose content changed") { options[:update] = true }
+        format_option(opts, options)
+      end
+      return EXIT_SUCCESS if parse(parser)
+
+      formatter_name = options[:format]
+      raise ConfigurationError, "cases file not found: #{options[:cases]}" unless File.file?(options[:cases])
+      if File.exist?(options[:output]) && !File.directory?(options[:output])
+        raise ConfigurationError, "output path is not a directory: #{options[:output]}"
+      end
+
+      boot(options)
+      registry = CaseRegistry.load(options[:cases])
+      entries = Snapshotter.new(registry: registry, output_dir: options[:output], update: options[:update]).call
+      @stdout.print(formatter_name == "json" ? snapshot_json(entries) : snapshot_text(entries))
+      EXIT_SUCCESS
+    end
+
+    def check
+      options = {
+        fixtures: DEFAULT_FIXTURES, boot: Boot::DEFAULT_PATH, environment: Boot::DEFAULT_ENVIRONMENT,
+        format: "text", fail_on_inconclusive: false
+      }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: jobpayload check [options]"
+        opts.on("--fixtures PATH", "Fixture directory or file (default: #{DEFAULT_FIXTURES})") { |v| options[:fixtures] = v }
+        boot_options(opts, options)
+        format_option(opts, options)
+        opts.on("--fail-on-inconclusive", "Exit 1 when any fixture is inconclusive") { options[:fail_on_inconclusive] = true }
+        opts.on("--debug", "Show exception backtraces in text output") { @debug = true }
+      end
+      return EXIT_SUCCESS if parse(parser)
+
+      files = FixtureLoader.files(options[:fixtures])
+      boot(options)
+      formatter = Formatter.for(options[:format])
+      result = Checker.new.call(FixtureLoader.parse(files))
+      @stdout.print(formatter.call(result, fail_on_inconclusive: options[:fail_on_inconclusive], debug: @debug))
+      result.exit_code(fail_on_inconclusive: options[:fail_on_inconclusive])
+    end
+
+    # Returns true when help or the version was printed (nothing else to do).
+    def parse(parser)
+      done = false
+      parser.on("-h", "--help", "Print this help") do
+        @stdout.print(parser.help)
+        done = true
+      end
+      # Replaces OptionParser's built-in --version, which would print
+      # "version unknown" and exit 1 (the compatibility-failure status).
+      parser.on("-v", "--version", "Print the version") do
+        @stdout.puts("jobpayload v#{VERSION}")
+        done = true
+      end
+      # Reject abbreviations such as --fail or --up: the option surface is a contract.
+      parser.require_exact = true
+      rest = parser.parse(@argv)
+      raise UsageError, "unexpected argument #{rest.first.inspect}" unless rest.empty? || done
+
+      done
+    end
+
+    def boot_options(opts, options)
+      opts.on("--boot PATH", "Application boot file (default: #{Boot::DEFAULT_PATH})") { |v| options[:boot] = v }
+      opts.on("--environment NAME", "RAILS_ENV to boot (default: #{Boot::DEFAULT_ENVIRONMENT})") do |v|
+        options[:environment] = v
+      end
+    end
+
+    def format_option(opts, options)
+      opts.on("--format FORMAT", Formatter::FORMATS, "Output format: #{Formatter::FORMATS.join('|')} (default: text)") do |v|
+        options[:format] = v
+      end
+    end
+
+    def boot(options)
+      if options[:environment] == "production"
+        @stderr.puts("jobpayload: warning: booting the production environment")
+      end
+      Boot.call(path: options[:boot], environment: options[:environment])
+    end
+
+    def snapshot_text(entries)
+      lines = entries.map do |entry|
+        line = format("%-9s %s  %s", entry.status, entry.name, JobPayload.scrub_utf8(entry.path))
+        entry.status == :skipped ? "#{line}  (exists and differs; pass --update to replace)" : line
+      end
+      counts = entries.map(&:status).tally
+      summary = %i[created updated identical skipped].map { |status| "#{counts.fetch(status, 0)} #{status}" }.join(", ")
+      "#{lines.join("\n")}\n\n#{entries.size} fixtures: #{summary}\n"
+    end
+
+    def snapshot_json(entries)
+      counts = entries.map(&:status).tally
+      document = {
+        "schema_version" => 1,
+        "tool_version" => VERSION,
+        "summary" => %i[created updated identical skipped].to_h { |status| [status.to_s, counts.fetch(status, 0)] },
+        "fixtures" => entries.map { |e| { "name" => e.name, "path" => JobPayload.scrub_utf8(e.path), "status" => e.status.to_s } }
+      }
+      Canonical.pretty(document)
+    end
+
+    def usage_error(message)
+      @stderr.puts("jobpayload: #{message}")
+      @stderr.puts("Run `jobpayload --help` for usage.")
+      EXIT_ERROR
+    end
+
+    def error(exception, prefix: "")
+      label = exception.is_a?(BootError) ? "AJP900 environment_error: " : ""
+      @stderr.puts("jobpayload: error: #{label}#{prefix}#{exception.message}")
+      if @debug
+        ExceptionClassifier.cause_chain(exception).each do |e|
+          @stderr.puts("  #{e.class}: #{e.message}")
+          Array(e.backtrace).each { |frame| @stderr.puts("      #{frame}") }
+        end
+      end
+      EXIT_ERROR
+    end
+  end
+end

data/lib/jobpayload/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # Base class for errors that abort a command with exit status 2
+  # (usage, configuration, boot or tool errors).
+  class Error < StandardError; end
+
+  # Invalid command line usage.
+  class UsageError < Error; end
+
+  # Invalid or missing input (cases file, fixture directory, case definitions).
+  class ConfigurationError < Error; end
+
+  # The host application could not be booted.
+  class BootError < Error; end
+end

data/lib/jobpayload/exception_classifier.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # Classifies an exception raised while deserializing a payload by looking at
+  # the classes in its cause chain (never primarily at message text).
+  #
+  # Classes are compared by name, including ancestors, so the classifier works
+  # whether or not a given library (Active Record, a database driver, ...) is
+  # loaded in the host application.
+  module ExceptionClassifier
+    # The referenced record does not exist. The payload may still be perfectly
+    # readable by the new code, so the result is inconclusive.
+    RECORD_MISSING = %w[
+      ActiveRecord::RecordNotFound
+      GlobalID::Locator::RecordNotFound
+      Mongoid::Errors::DocumentNotFound
+    ].freeze
+
+    # The check environment itself is broken (no database, no connection,
+    # schema not loaded...). ActiveRecord::StatementInvalid is included because
+    # SQL errors while locating a record mean the test database does not match
+    # the application, not that the payload is unreadable. SystemStackError is
+    # included because exhausting the Ruby stack (pathologically deep payloads)
+    # means jobpayload could not finish the check, not that the payload is
+    # incompatible.
+    ENVIRONMENT = %w[
+      ActiveRecord::ConnectionNotEstablished
+      ActiveRecord::NoDatabaseError
+      ActiveRecord::StatementInvalid
+      ActiveRecord::DatabaseConnectionError
+      ActiveRecord::PendingMigrationError
+      ActiveRecord::AdapterNotSpecified
+      ActiveRecord::AdapterNotFound
+      PG::ConnectionBad
+      Mysql2::Error::ConnectionError
+      Trilogy::ConnectionError
+      SQLite3::CantOpenException
+      Errno::ECONNREFUSED
+      SystemStackError
+    ].freeze
+
+    MAX_CHAIN_LENGTH = 32
+
+    module_function
+
+    # Returns :environment, :record_missing or :failure.
+    def call(exception)
+      names = cause_chain(exception).flat_map { |e| ancestor_names(e) }
+      return :environment if names.intersect?(ENVIRONMENT)
+      return :record_missing if names.intersect?(RECORD_MISSING)
+
+      :failure
+    end
+
+    # The exception followed by its causes, outermost first. Stops on cycles.
+    def cause_chain(exception)
+      chain = []
+      seen = {}.compare_by_identity
+      current = exception
+      while current && !seen.key?(current) && chain.size < MAX_CHAIN_LENGTH
+        seen[current] = true
+        chain << current
+        current = current.cause
+      end
+      chain
+    end
+
+    def ancestor_names(exception)
+      exception.class.ancestors.filter_map { |mod| mod.is_a?(Class) ? mod.name : nil }
+    end
+
+    # Name of the exception's class; anonymous classes fall back to the
+    # nearest named ancestor so reports never show an empty class.
+    def class_name(exception)
+      exception.class.ancestors.find { |mod| mod.is_a?(Class) && mod.name }&.name.to_s
+    end
+
+    # Exception#message can itself raise (or return non-strings) for badly
+    # behaved exception classes; never let that crash the report.
+    # Always valid UTF-8, so JSON output never fails on a message carrying
+    # binary or otherwise invalid bytes (they become U+FFFD).
+    def safe_message(exception)
+      JobPayload.scrub_utf8(exception.message.to_s)
+    rescue StandardError => e
+      "(message unavailable: #{e.class})"
+    end
+  end
+end