jobpayload 0.1.0

data/lib/jobpayload/finding.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # One problem found while checking a fixture.
+  #
+  # Finding codes are a stable API: their meaning does not change within 0.1.x.
+  Finding = Struct.new(
+    :code,
+    :fixture,
+    :job_class,
+    :argument_path,
+    :message,
+    :exception_class,
+    :exception_message,
+    :cause_chain, # Array of {"class" => String, "message" => String}, outermost first
+    :backtraces,  # Array of Array<String>, parallel to cause_chain; never serialized to JSON
+    keyword_init: true
+  )
+
+  class Finding
+    # code => [name, kind]. kind is :breaking, :inconclusive or :fatal.
+    CODES = {
+      "AJP001" => ["fixture_invalid", :fatal],
+      "AJP101" => ["unknown_job_class", :breaking],
+      "AJP102" => ["job_deserialize_failed", :breaking],
+      "AJP201" => ["argument_deserialize_failed", :breaking],
+      "AJP202" => ["globalid_record_missing", :inconclusive],
+      "AJP900" => ["environment_error", :fatal]
+    }.freeze
+
+    # Severity strings used in JSON output.
+    SEVERITIES = { breaking: "error", inconclusive: "warning", fatal: "fatal" }.freeze
+
+    def self.build(code:, fixture:, message:, job_class: nil, argument_path: nil, exception: nil)
+      raise ArgumentError, "unknown finding code #{code}" unless CODES.key?(code)
+
+      chain = exception ? ExceptionClassifier.cause_chain(exception) : []
+      new(
+        code: code,
+        fixture: fixture,
+        job_class: job_class,
+        argument_path: argument_path,
+        message: message,
+        exception_class: exception && ExceptionClassifier.class_name(exception),
+        exception_message: exception && ExceptionClassifier.safe_message(exception),
+        cause_chain: chain.map { |e| { "class" => ExceptionClassifier.class_name(e), "message" => ExceptionClassifier.safe_message(e) } },
+        backtraces: chain.map { |e| Array(e.backtrace) }
+      )
+    end
+
+    def name
+      CODES.fetch(code).first
+    end
+
+    def kind
+      CODES.fetch(code).last
+    end
+
+    def severity
+      SEVERITIES.fetch(kind)
+    end
+
+    def sort_key
+      [fixture.to_s, code, argument_path.to_s, message.to_s]
+    end
+
+    def to_json_hash
+      {
+        "code" => code,
+        "name" => name,
+        "severity" => severity,
+        "fixture" => fixture,
+        "job_class" => job_class,
+        "argument_path" => argument_path,
+        "message" => message,
+        "exception_class" => exception_class,
+        "exception_message" => exception_message,
+        "cause_chain" => cause_chain
+      }
+    end
+  end
+end

data/lib/jobpayload/fixture.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JobPayload
+  # A parsed fixture file (schema v1).
+  #
+  # Fixture.parse never raises for bad content: it returns an Invalid value
+  # carrying the reason, which the checker reports as AJP001.
+  class Fixture
+    Invalid = Struct.new(:name, :path, :reason)
+
+    attr_reader :name, :path, :job, :source
+
+    def initialize(name:, path:, job:, source:)
+      @name = name
+      @path = path
+      @job = job
+      @source = source
+    end
+
+    def job_class
+      job["job_class"]
+    end
+
+    def self.parse(path)
+      basename = File.basename(path, ".json")
+      reason = catch(:invalid) do
+        data = parse_json(path)
+        validate!(data, basename)
+        return new(name: data["name"], path: path, job: data["job"], source: data["source"])
+      end
+      # The file name and OS error messages may carry bytes that are not
+      # UTF-8; Invalid values end up in JSON output.
+      Invalid.new(JobPayload.scrub_utf8(basename), path, JobPayload.scrub_utf8(reason))
+    end
+
+    def self.parse_json(path)
+      content = File.binread(path).force_encoding(Encoding::UTF_8)
+      invalid!("file is not valid UTF-8") unless content.valid_encoding?
+      data = JSON.parse(content, max_nesting: false)
+      # Some json versions decode a lone surrogate escape ("\udc80") into
+      # bytes that are not valid UTF-8.
+      invalid!("file contains a string escape that is not valid UTF-8") unless valid_strings?(data)
+      data
+    rescue JSON::ParserError => e
+      invalid!("invalid JSON: #{e.message.lines.first.to_s.strip}")
+    rescue SystemCallError => e
+      invalid!("cannot read file: #{e.message}")
+    end
+
+    # Iterative, so that deeply nested fixtures cannot exhaust the stack here.
+    def self.valid_strings?(data)
+      pending = [data]
+      until pending.empty?
+        value = pending.pop
+        case value
+        when String then return false unless value.valid_encoding?
+        when Array then pending.concat(value)
+        when Hash
+          pending.concat(value.keys)
+          pending.concat(value.values)
+        end
+      end
+      true
+    end
+
+    def self.validate!(data, basename)
+      invalid!("top-level JSON value must be an object") unless data.is_a?(Hash)
+      invalid!("missing jobpayload_schema") unless data.key?("jobpayload_schema")
+      schema = data["jobpayload_schema"]
+      unless schema == FIXTURE_SCHEMA && schema.is_a?(Integer)
+        invalid!("unsupported jobpayload_schema #{schema.inspect} (expected #{FIXTURE_SCHEMA})")
+      end
+      invalid!("invalid file name #{basename.inspect}.json") unless JobPayload.valid_name?(basename)
+
+      name = data["name"]
+      invalid!("name must be a string") unless name.is_a?(String)
+      invalid!("invalid name #{name.inspect}") unless JobPayload.valid_name?(name)
+      invalid!("name #{name.inspect} does not match file name #{basename}.json") unless name == basename
+      invalid!("source must be an object") if data.key?("source") && !data["source"].is_a?(Hash)
+
+      job = data["job"]
+      invalid!("job must be an object") unless job.is_a?(Hash)
+      invalid!("job.job_class must be a non-empty string") unless job["job_class"].is_a?(String) && !job["job_class"].empty?
+      invalid!("job.arguments must be an array") unless job["arguments"].is_a?(Array)
+    end
+
+    def self.invalid!(reason)
+      throw :invalid, reason
+    end
+    private_class_method :parse_json, :valid_strings?, :validate!, :invalid!
+  end
+end

data/lib/jobpayload/fixture_loader.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # Resolves --fixtures (a directory or a single file) into fixture files, in a
+  # stable order that does not depend on directory enumeration order.
+  #
+  # Listing (.files) only touches the file system, so it runs before the host
+  # application boots; parsing (.parse) needs the json library and runs after
+  # boot, so the application's own json version is the one that gets loaded.
+  module FixtureLoader
+    module_function
+
+    def files(path)
+      files =
+        if File.directory?(path)
+          Dir.children(path).select { |entry| entry.end_with?(".json") }.sort.map { |entry| File.join(path, entry) }
+            .select { |file| File.file?(file) }
+        elsif File.file?(path)
+          [path]
+        else
+          raise ConfigurationError, "fixture path not found: #{path}"
+        end
+      raise ConfigurationError, "no fixture files (*.json) found in #{path}" if files.empty?
+
+      files
+    end
+
+    def parse(files)
+      files.map { |file| Fixture.parse(file) }
+    end
+
+    def call(path)
+      parse(files(path))
+    end
+  end
+end

data/lib/jobpayload/formatter/json.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JobPayload
+  module Formatter
+    # Machine-readable output, schema v1. Field names and meanings are stable
+    # for 0.1.x; see README "JSON output".
+    module JSON
+      SCHEMA_VERSION = 1
+
+      module_function
+
+      def call(result, fail_on_inconclusive: false, debug: false) # rubocop:disable Lint/UnusedMethodArgument
+        document = {
+          "schema_version" => SCHEMA_VERSION,
+          "tool_version" => VERSION,
+          "status" => result.status(fail_on_inconclusive: fail_on_inconclusive),
+          "summary" => result.summary,
+          "fixtures" => result.fixture_results.map { |r| { "name" => r.name, "status" => r.status.to_s } },
+          "findings" => result.findings.map(&:to_json_hash)
+        }
+        Canonical.pretty(document)
+      end
+    end
+  end
+end

data/lib/jobpayload/formatter/text.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module JobPayload
+  module Formatter
+    # Human-readable output. Ordering is fully determined by fixture name,
+    # finding code and argument path.
+    module Text
+      LABELS = { breaking: "breaking", inconclusive: "inconclusive", fatal: "fatal" }.freeze
+
+      NOTES = {
+        "AJP202" => "This does not by itself prove a payload compatibility break."
+      }.freeze
+
+      module_function
+
+      def call(result, fail_on_inconclusive: false, debug: false) # rubocop:disable Lint/UnusedMethodArgument
+        blocks = result.fixture_results.flat_map do |fixture_result|
+          if fixture_result.findings.empty?
+            ["PASS #{fixture_result.name}\n"]
+          else
+            fixture_result.findings.sort_by(&:sort_key).map { |finding| finding_block(finding, debug: debug) }
+          end
+        end
+        out = +""
+        blocks.each_with_index do |block, index|
+          previous = blocks[index - 1] if index.positive?
+          # Keep consecutive PASS lines together; separate multi-line blocks.
+          out << "\n" if previous && (multiline?(block) || multiline?(previous))
+          out << block
+        end
+        out << "\n" << summary(result)
+      end
+
+      def multiline?(block)
+        block.count("\n") > 1
+      end
+
+      def finding_block(finding, debug:)
+        lines = ["#{finding.code} #{LABELS.fetch(finding.kind)} #{finding.fixture}", ""]
+        if finding.job_class
+          lines += ["Job:", "  #{finding.job_class}", ""]
+        end
+        if finding.argument_path
+          lines += ["Argument:", "  #{finding.argument_path}", ""]
+        end
+        lines << finding.message
+        if (note = NOTES[finding.code])
+          lines += ["", note]
+        end
+        if (root = finding.cause_chain.last)
+          lines += ["", "Cause:", "  #{root['class']}: #{root['message']}"]
+        end
+        lines += debug_lines(finding) if debug
+        "#{lines.join("\n")}\n"
+      end
+
+      def debug_lines(finding)
+        return [] if finding.cause_chain.empty?
+
+        lines = ["", "Cause chain:"]
+        finding.cause_chain.each_with_index do |cause, index|
+          lines << "  #{index + 1}. #{cause['class']}: #{cause['message']}"
+          finding.backtraces.fetch(index, []).each { |frame| lines << "       #{frame}" }
+        end
+        lines
+      end
+
+      def summary(result)
+        counts = result.summary
+        lines = [
+          "#{counts['fixtures']} fixtures checked",
+          "#{counts['compatible']} compatible",
+          "#{counts['incompatible']} incompatible",
+          "#{counts['inconclusive']} inconclusive"
+        ]
+        tool_errors = counts["tool_errors"]
+        lines << "#{tool_errors} tool error#{'s' unless tool_errors == 1}" if tool_errors.positive?
+        "#{lines.join("\n")}\n"
+      end
+    end
+  end
+end

data/lib/jobpayload/formatter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # Output formatters for `check` results.
+  module Formatter
+    autoload :Text, "jobpayload/formatter/text"
+    autoload :JSON, "jobpayload/formatter/json"
+
+    FORMATS = %w[text json].freeze
+
+    def self.for(name)
+      case name
+      when "text" then Text
+      when "json" then JSON
+      else raise UsageError, "unknown format #{name.inspect} (expected one of: #{FORMATS.join(', ')})"
+      end
+    end
+  end
+end

data/lib/jobpayload/result.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # Outcome of a `check` run.
+  class Result
+    # Per-fixture outcome. status is :pass, :fail, :inconclusive or
+    # :tool_error (the worst finding wins).
+    FixtureResult = Struct.new(:name, :path, :findings) do
+      def status
+        kinds = findings.map(&:kind)
+        if kinds.include?(:fatal) then :tool_error
+        elsif kinds.include?(:breaking) then :fail
+        elsif kinds.include?(:inconclusive) then :inconclusive
+        else :pass
+        end
+      end
+    end
+
+    EXIT_SUCCESS = 0
+    EXIT_FAILURE = 1
+    EXIT_ERROR = 2
+
+    attr_reader :fixture_results
+
+    def initialize(fixture_results)
+      @fixture_results = fixture_results
+    end
+
+    # All findings, sorted by fixture, code, then argument path.
+    def findings
+      fixture_results.flat_map(&:findings).sort_by(&:sort_key)
+    end
+
+    def summary
+      counts = fixture_results.map(&:status).tally
+      {
+        "fixtures" => fixture_results.size,
+        "compatible" => counts.fetch(:pass, 0),
+        "incompatible" => counts.fetch(:fail, 0),
+        "inconclusive" => counts.fetch(:inconclusive, 0),
+        "tool_errors" => counts.fetch(:tool_error, 0)
+      }
+    end
+
+    # "pass", "fail" or "tool_error".
+    def status(fail_on_inconclusive: false)
+      statuses = fixture_results.map(&:status)
+      if statuses.include?(:tool_error) then "tool_error"
+      elsif statuses.include?(:fail) then "fail"
+      elsif fail_on_inconclusive && statuses.include?(:inconclusive) then "fail"
+      else "pass"
+      end
+    end
+
+    def exit_code(fail_on_inconclusive: false)
+      { "tool_error" => EXIT_ERROR, "fail" => EXIT_FAILURE, "pass" => EXIT_SUCCESS }
+        .fetch(status(fail_on_inconclusive: fail_on_inconclusive))
+    end
+  end
+end

data/lib/jobpayload/snapshotter.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module JobPayload
+  # Turns snapshot cases into fixture files.
+  #
+  # The source of truth is ActiveJob::Base#serialize. Volatile Active Job
+  # metadata is replaced with fixed values so repeated snapshots are
+  # byte-for-byte identical; every other key (including keys added by a job's
+  # own #serialize override) is kept as-is.
+  class Snapshotter
+    CANONICAL_JOB_ID = "00000000-0000-0000-0000-000000000000"
+    CANONICAL_TIME = "2000-01-01T00:00:00.000000000Z"
+
+    # Volatile keys and the stable values they are replaced with. Keys are only
+    # replaced when present, so the shape of #serialize is never changed.
+    NORMALIZED = {
+      "job_id" => CANONICAL_JOB_ID,
+      "provider_job_id" => nil,
+      "enqueued_at" => CANONICAL_TIME,
+      "executions" => 0,
+      "exception_executions" => {}
+    }.freeze
+
+    Entry = Struct.new(:name, :path, :status) # status: :created, :identical, :updated, :skipped
+
+    def initialize(registry:, output_dir:, update: false)
+      @registry = registry
+      @output_dir = output_dir
+      @update = update
+    end
+
+    # Generates every fixture in memory first, so a failing case leaves the
+    # fixture directory untouched, then writes them in name order.
+    def call
+      documents = @registry.cases.map { |kase| [kase.name, Canonical.generate(build_document(kase))] }
+      begin
+        FileUtils.mkdir_p(@output_dir)
+      rescue SystemCallError => e
+        raise ConfigurationError, "cannot create output directory #{@output_dir}: #{e.message}"
+      end
+      documents.map { |name, content| write(name, content) }
+    end
+
+    def build_document(kase)
+      {
+        "jobpayload_schema" => FIXTURE_SCHEMA,
+        "name" => kase.name,
+        "source" => self.class.source_versions,
+        "job" => serialize_case(kase)
+      }
+    end
+
+    def self.normalize(job_data)
+      data = job_data.to_h { |key, value| [key.to_s, value] }
+      NORMALIZED.each { |key, value| data[key] = Canonical.deep_copy(value) if data.key?(key) }
+      data["scheduled_at"] = CANONICAL_TIME if data.key?("scheduled_at") && !data["scheduled_at"].nil?
+      # Round-trip through JSON so the fixture holds exactly what a queue would store.
+      JSON.parse(JSON.generate(data))
+    end
+
+    def self.source_versions
+      {
+        "ruby_version" => RUBY_VERSION,
+        "active_job_version" => active_job_version,
+        "rails_version" => rails_version,
+        "jobpayload_version" => VERSION
+      }
+    end
+
+    def self.active_job_version
+      spec = Gem.loaded_specs["activejob"]
+      return spec.version.to_s if spec
+      return ::ActiveJob.version.to_s if defined?(::ActiveJob) && ::ActiveJob.respond_to?(:version)
+
+      nil
+    end
+
+    def self.rails_version
+      return nil unless defined?(::Rails) && ::Rails.respond_to?(:version)
+
+      ::Rails.version.to_s
+    end
+
+    private
+
+    # Runs the case block and serializes the job it returns. Any error is
+    # reported against the case, never as an internal error.
+    def serialize_case(kase)
+      job = kase.block.call
+      unless job.is_a?(::ActiveJob::Base)
+        raise ConfigurationError,
+          "fixture #{kase.name.inspect} (#{kase.location}) must return an ActiveJob::Base instance, got #{job.class}"
+      end
+
+      self.class.normalize(job.serialize)
+    rescue ConfigurationError
+      raise
+    rescue StandardError, ScriptError => e
+      raise ConfigurationError, "fixture #{kase.name.inspect} (#{kase.location}) raised #{e.class}: #{e.message}"
+    end
+
+    def write(name, content)
+      path = File.join(@output_dir, "#{name}.json")
+      status =
+        if !File.exist?(path)
+          :created
+        elsif File.binread(path) == content.b
+          :identical
+        elsif @update
+          :updated
+        else
+          :skipped
+        end
+      Canonical.atomic_write(path, content) if %i[created updated].include?(status)
+      Entry.new(name, path, status)
+    rescue SystemCallError => e
+      raise ConfigurationError, "cannot write fixture #{path}: #{e.message}"
+    end
+  end
+end

data/lib/jobpayload/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JobPayload
+  VERSION = "0.1.0"
+end

data/lib/jobpayload.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Entry point for the jobpayload gem.
+#
+# This file is intentionally lightweight: requiring it must not load Active Job
+# (or any other part of the host application's framework). Active Job APIs are
+# referenced lazily, only after the host application has been booted, so that
+# custom serializer registration and initializer order are left untouched.
+require_relative "jobpayload/version"
+require_relative "jobpayload/errors"
+require_relative "jobpayload/case_registry"
+
+module JobPayload
+  autoload :CLI, "jobpayload/cli"
+  autoload :Boot, "jobpayload/boot"
+  autoload :Canonical, "jobpayload/canonical"
+  autoload :Snapshotter, "jobpayload/snapshotter"
+  autoload :Fixture, "jobpayload/fixture"
+  autoload :FixtureLoader, "jobpayload/fixture_loader"
+  autoload :Checker, "jobpayload/checker"
+  autoload :Result, "jobpayload/result"
+  autoload :Finding, "jobpayload/finding"
+  autoload :ExceptionClassifier, "jobpayload/exception_classifier"
+  autoload :Formatter, "jobpayload/formatter"
+
+  # Pattern every fixture name must match. Rejects path separators, leading
+  # dots and anything else that could escape the fixture directory.
+  NAME_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9._-]*\z/
+
+  # Fixture wrapper schema version written by `snapshot` and read by `check`.
+  FIXTURE_SCHEMA = 1
+
+  # Defines snapshot cases. Called from the cases file (test/jobpayload_cases.rb
+  # by default) while `jobpayload snapshot` is loading it.
+  #
+  #   JobPayload.define do
+  #     fixture "billing-money-v1" do
+  #       BillingJob.new(Money.new(1_250, "USD"))
+  #     end
+  #   end
+  def self.define(&block)
+    CaseRegistry.current.define(&block)
+  end
+
+  def self.valid_name?(name)
+    name.is_a?(String) && NAME_PATTERN.match?(name) && !name.include?("..")
+  end
+
+  # Returns +string+ as valid UTF-8 (invalid bytes become U+FFFD), for text
+  # from outside jobpayload (exception messages, file names, paths) that ends
+  # up in JSON output.
+  def self.scrub_utf8(string)
+    if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(string.encoding)
+      string.dup.force_encoding(Encoding::UTF_8).scrub("\uFFFD")
+    else
+      string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+    end
+  rescue EncodingError # no converter (for example UTF-7): keep the bytes
+    string.b.force_encoding(Encoding::UTF_8).scrub("\uFFFD")
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: jobpayload
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- cottondesu
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: |
+  jobpayload snapshots Active Job serialized job data (ActiveJob::Base#serialize) into
+  deterministic JSON fixtures and checks that the current application can still
+  deserialize them (ActiveJob::Base.deserialize and ActiveJob::Arguments.deserialize)
+  without ever performing the job.
+executables:
+- jobpayload
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/jobpayload
+- lib/jobpayload.rb
+- lib/jobpayload/boot.rb
+- lib/jobpayload/canonical.rb
+- lib/jobpayload/case_registry.rb
+- lib/jobpayload/checker.rb
+- lib/jobpayload/cli.rb
+- lib/jobpayload/errors.rb
+- lib/jobpayload/exception_classifier.rb
+- lib/jobpayload/finding.rb
+- lib/jobpayload/fixture.rb
+- lib/jobpayload/fixture_loader.rb
+- lib/jobpayload/formatter.rb
+- lib/jobpayload/formatter/json.rb
+- lib/jobpayload/formatter/text.rb
+- lib/jobpayload/result.rb
+- lib/jobpayload/snapshotter.rb
+- lib/jobpayload/version.rb
+homepage: https://github.com/cottondesu/jobpayload
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cottondesu/jobpayload
+  source_code_uri: https://github.com/cottondesu/jobpayload
+  changelog_uri: https://github.com/cottondesu/jobpayload/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Checks that previously serialized Active Job payloads still deserialize on
+  new code.
+test_files: []