rspec-hopper 0.1.0

data/lib/rspec/hopper/example_reset.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+
+module RSpec
+  module Hopper
+    # Makes completed examples rerunnable in the same process.
+    #
+    # rspec-core does not expose a per-example reset: `@exception` is set once
+    # and never cleared by `run`, `finish` reports failure whenever it is
+    # present, and the ExecutionResult in metadata is mutated in place. This is
+    # the one sanctioned touch of Example internals (see the product spec,
+    # "Retry state isolation"). It changes no method resolution, so it cannot
+    # collide with gems that prepend onto Example.
+    module ExampleReset
+      # Pinned after a run under bare rspec-core; the contract spec fails loudly
+      # if a patch release adds state we would have to reset too.
+      EXPECTED_IVARS = %i[
+        @clock @example_block @example_group_class @example_group_instance @exception @id @metadata @reporter
+      ].freeze
+
+      module_function
+
+      # Resets every selected example in the given top-level groups and all of
+      # their descendants. Returns the number of examples reset.
+      def reset(example_groups)
+        Array(example_groups).sum do |group|
+          group.descendants.sum do |descendant|
+            descendant.filtered_examples.each { |example| reset_example(example) }.size
+          end
+        end
+      end
+
+      def reset_example(example)
+        example.instance_variable_set(:@exception, nil)
+        example.metadata[:execution_result] = RSpec::Core::Example::ExecutionResult.new
+        example
+      end
+    end
+  end
+end

data/lib/rspec/hopper/fingerprint.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module RSpec
+  module Hopper
+    # Proves that workers loaded the same logical suite, not merely that they were
+    # given the same arguments. Computed after loading, over the normalized
+    # selection inputs, the ordering strategy name (never the seed), the sorted
+    # selected example ids and the optional revision string.
+    class Fingerprint
+      INPUT_KEYS = %w[file_args filter pattern exclude_pattern order example_ids revision].freeze
+      PROC_ADDRESS = /0x[0-9a-f]+@?/
+      # Per-input digests are recorded in the manifest so a mismatching worker
+      # can name the inputs that differ. Truncated: they are compared with each
+      # other, never used as a security boundary, and `meta` stays small.
+      DIGEST_LENGTH = 16
+
+      attr_reader :value, :inputs
+
+      class << self
+        # @param configuration [RSpec::Core::Configuration] the configured RSpec
+        # @param options [RSpec::Core::ConfigurationOptions] the merged options
+        # @param example_ids [Array<String>] ids of the selected examples
+        # @param file_args [Array<String>] normalized file arguments
+        # @param revision [String, nil]
+        def compute(configuration:, options:, example_ids:, file_args:, revision: nil)
+          filter_manager = configuration.filter_manager
+          new(
+            "file_args" => Array(file_args).map(&:to_s).sort,
+            "filter" => {
+              "inclusions" => render_rules(filter_manager.inclusions.rules),
+              "exclusions" => render_rules(filter_manager.exclusions.rules)
+            },
+            "pattern" => configuration.pattern.to_s,
+            "exclude_pattern" => configuration.exclude_pattern.to_s,
+            "order" => ordering_name(options.options[:order]),
+            "example_ids" => Array(example_ids).map(&:to_s).sort,
+            "revision" => revision&.to_s
+          )
+        end
+
+        # The strategy name of an `--order` option value, without any seed.
+        def ordering_name(option)
+          name = option.to_s.split(":").first.to_s
+          return "defined" if name.empty?
+
+          name.include?("rand") ? "random" : name
+        end
+
+        # Filter rules as deterministic strings: proc addresses are stripped and
+        # the project directory (locations are absolute) is replaced by ".".
+        def render_rules(rules)
+          project_dir = File.expand_path(".")
+          rules.map { |key, value| "#{key}=#{render_value(value)}".gsub(PROC_ADDRESS, "").gsub(project_dir, ".") }.sort
+        end
+
+        # Renders a filter value without going through the built-in `inspect`
+        # for containers. Ruby 3.4 changed `Hash#inspect` from `{"a"=>1}` to
+        # `{"a" => 1}`, which would otherwise make the same suite fingerprint
+        # differently on either side of that release. Hash pairs are sorted so
+        # insertion order cannot change the result either.
+        def render_value(value)
+          case value
+          when Hash
+            pairs = value.map { |k, v| "#{render_value(k)} => #{render_value(v)}" }.sort
+            "{#{pairs.join(", ")}}"
+          when Array
+            "[#{value.map { |element| render_value(element) }.join(", ")}]"
+          else
+            value.inspect
+          end
+        end
+
+        # A short digest of one input value, stable across Ruby versions
+        # because `render_value` already avoids the built-in container inspect.
+        def digest(value)
+          Digest::SHA256.hexdigest(JSON.generate([canonical(value)]))[0, DIGEST_LENGTH]
+        end
+
+        def canonical(object)
+          case object
+          when Hash then object.keys.map(&:to_s).sort.to_h { |k| [k, canonical(object[k] || object[k.to_sym])] }
+          when Array then object.map { |v| canonical(v) }
+          else object
+          end
+        end
+      end
+
+      def initialize(inputs)
+        @inputs = self.class.canonical(inputs).freeze
+        @value = Digest::SHA256.hexdigest(JSON.generate(@inputs)).freeze
+      end
+
+      def to_s = value
+
+      def ==(other)
+        value == (other.is_a?(Fingerprint) ? other.value : other)
+      end
+      alias eql? ==
+
+      def hash = value.hash
+
+      def to_json(*) = JSON.generate(inputs, *)
+
+      # The manifest records these, not the inputs themselves: the sorted
+      # example-id list of a real suite is hundreds of kilobytes, and `meta`
+      # has to stay small. Digests name the inputs that differ; the example-id
+      # count turns "example_ids differ" into something an operator can act on.
+      def digests
+        @digests ||= INPUT_KEYS.to_h { |key| [key, self.class.digest(inputs[key])] }
+                               .merge("example_ids_count" => inputs["example_ids"].size)
+                               .freeze
+      end
+
+      # One line describing the inputs, for mismatch messages.
+      def summary
+        [
+          "file_args=#{inputs["file_args"].inspect}",
+          "filter=#{inputs["filter"].inspect}",
+          "pattern=#{inputs["pattern"].inspect}",
+          "exclude_pattern=#{inputs["exclude_pattern"].inspect}",
+          "order=#{inputs["order"]}",
+          "example_ids=#{inputs["example_ids"].size}",
+          "revision=#{inputs["revision"].inspect}"
+        ].join(", ")
+      end
+
+      # Explains why a worker's fingerprint differs from the manifest's.
+      module Mismatch
+        module_function
+
+        # @param local [Fingerprint] this worker's fingerprint
+        # @param remote_value [String] the manifest's fingerprint
+        # @param remote_digests [String, Hash, nil] the initializer's per-input
+        #   digests, as recorded in the manifest, when available
+        def explain(local, remote_value, remote_digests = nil)
+          lines = ["suite fingerprint mismatch: this worker computed #{local.value} " \
+                   "but the build manifest records #{remote_value}"]
+          remote = parse(remote_digests)
+          lines.concat(differences(local.digests, remote)) if remote
+          lines << "local inputs: #{local.summary}"
+          lines.join("\n")
+        end
+
+        # Names the inputs whose digests differ. Only the example ids carry a
+        # count, because that is the difference an operator cannot see from
+        # their own command line: a stale checkout selecting a different set.
+        def differences(local, remote)
+          keys = Fingerprint::INPUT_KEYS.reject { |key| local[key] == remote[key] }
+          if keys.empty?
+            return ["recorded inputs are identical; the fingerprint algorithm may differ between gem versions"]
+          end
+
+          lines = ["differing inputs: #{keys.join(", ")}"]
+          lines << "  #{example_id_counts(local, remote)}" if keys.include?("example_ids")
+          lines
+        end
+
+        # Equal counts with differing digests mean a checkout that renames or
+        # moves examples rather than one that adds or removes them.
+        def example_id_counts(local, remote)
+          mine = local["example_ids_count"]
+          theirs = remote["example_ids_count"]
+          return "example_ids: this worker selects #{mine}, the initializer selected #{theirs}" unless mine == theirs
+
+          "example_ids: this worker and the initializer both select #{mine}, but the ids differ"
+        end
+
+        def parse(remote_digests)
+          case remote_digests
+          when nil, "" then nil
+          when Hash then remote_digests.transform_keys(&:to_s)
+          else
+            parsed = JSON.parse(remote_digests.to_s)
+            parsed.is_a?(Hash) ? parsed.transform_keys(&:to_s) : nil
+          end
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rspec/hopper/keys.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Hopper
+    # Redis key names for one build. The braces are a Redis Cluster hash tag so
+    # every key of a build shares a slot.
+    class Keys
+      LIVE = %w[units units:priority attempts meta unit_state workers].freeze
+      ALL = (LIVE + %w[leader exists]).freeze
+      CONSUMER_GROUP = "workers"
+
+      attr_reader :build_id, :prefix
+
+      def initialize(build_id)
+        @build_id = build_id
+        @prefix = "hopper:{#{build_id}}:"
+      end
+
+      def pattern = "#{@prefix}*"
+      def units = key("units")
+      def units_priority = key("units:priority")
+      def attempts = key("attempts")
+      def meta = key("meta")
+      def unit_state = key("unit_state")
+      def workers = key("workers")
+      def leader = key("leader")
+      def exists = key("exists")
+
+      def key(name) = "#{@prefix}#{name}"
+
+      # Full key for a short stream name carried in a Reservation.
+      def stream(short) = key(short)
+
+      def live = LIVE.map { |n| key(n) }
+      def all = ALL.map { |n| key(n) }
+    end
+  end
+end

data/lib/rspec/hopper/manifest.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RSpec
+  module Hopper
+    # Written once by the initializing worker into `meta`. Unit ids are the keys
+    # of `file_counts` in order; they are not stored separately.
+    Manifest = Data.define(
+      :total_units, :total_examples, :file_counts, :file_args,
+      :fingerprint, :fingerprint_digests, :seed, :ready_at, :revision, :load_errors
+    ) do
+      # Builds a Manifest from `meta` exactly as HGETALL returns it (all string
+      # values). Runtime fields such as `state` and `finalized_count` are ignored.
+      def self.from_meta(meta)
+        meta = meta.transform_keys(&:to_s)
+        new(
+          total_units: meta.fetch("total_units"),
+          total_examples: meta.fetch("total_examples"),
+          file_counts: JSON.parse(meta.fetch("file_counts", "{}")),
+          file_args: JSON.parse(meta.fetch("file_args", "[]")),
+          fingerprint: meta["fingerprint"],
+          fingerprint_digests: parse_digests(meta["fingerprint_digests"]),
+          seed: meta["seed"],
+          ready_at: meta["ready_at"],
+          revision: meta["revision"],
+          load_errors: JSON.parse(meta.fetch("load_errors", "[]"))
+        )
+      end
+
+      # Per-input digests of the initializer's fingerprint, for mismatch
+      # messages; absent from builds initialized by an older worker.
+      def self.parse_digests(value)
+        return nil if value.nil? || value.empty?
+
+        digests = JSON.parse(value)
+        digests.is_a?(Hash) ? digests : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Optional fields are nil when absent rather than empty strings, so a
+      # manifest read back from `meta` equals the one that was written.
+      def self.normalize_optional(fingerprint:, fingerprint_digests:, seed:, ready_at:, revision:)
+        {
+          fingerprint: presence(fingerprint)&.to_s,
+          fingerprint_digests: presence(fingerprint_digests)&.transform_keys(&:to_s)&.freeze,
+          seed: presence(seed)&.then { |s| Integer(s) },
+          ready_at: presence(ready_at)&.then { |ms| Integer(ms) },
+          revision: presence(revision)&.to_s
+        }
+      end
+
+      def self.presence(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) ? nil : value
+      end
+
+      def initialize(total_examples:, file_counts:, file_args:, fingerprint: nil, fingerprint_digests: nil,
+                     seed: nil, total_units: file_counts.size, ready_at: nil, revision: nil, load_errors: [])
+        counts = file_counts.to_h { |path, count| [path.to_s, Integer(count)] }.freeze
+        units = Integer(total_units)
+        if units != counts.size
+          raise ArgumentError, "total_units (#{units}) does not match file_counts.size (#{counts.size})"
+        end
+
+        super(
+          total_units: units,
+          total_examples: Integer(total_examples),
+          file_counts: counts,
+          file_args: Array(file_args).map(&:to_s).freeze,
+          load_errors: Array(load_errors).map(&:to_s).freeze,
+          **self.class.normalize_optional(fingerprint: fingerprint, fingerprint_digests: fingerprint_digests,
+                                          seed: seed, ready_at: ready_at, revision: revision)
+        )
+      end
+
+      def unit_ids = file_counts.keys
+
+      def init_failed? = load_errors.any?
+
+      def empty? = total_examples.zero?
+
+      # Hash of String => String for HSET. Nested fields are JSON-encoded;
+      # nil fields are omitted rather than written as empty strings.
+      def to_meta
+        meta = {
+          "total_units" => total_units.to_s,
+          "total_examples" => total_examples.to_s,
+          "file_counts" => JSON.generate(file_counts),
+          "file_args" => JSON.generate(file_args),
+          "load_errors" => JSON.generate(load_errors)
+        }
+        optional_meta.each { |key, value| meta[key] = value unless value.nil? }
+        meta
+      end
+
+      def to_json(*args) = to_h.to_json(*args)
+
+      private
+
+      # Written only when set; an absent field must not become an empty string.
+      def optional_meta
+        {
+          "fingerprint" => fingerprint,
+          "fingerprint_digests" => fingerprint_digests && JSON.generate(fingerprint_digests),
+          "seed" => seed&.to_s,
+          "ready_at" => ready_at&.to_s,
+          "revision" => revision
+        }
+      end
+    end
+  end
+end

data/lib/rspec/hopper/queue/redis_streams/lua/init.lua

@@ -0,0 +1,94 @@
+-- Build initialization. Publishes the manifest exactly once per build id.
+--
+-- KEYS: units, units:priority, attempts, meta, unit_state, leader, exists
+-- ARGV: mode ("success" | "failure"), lease token, ttl_ms, tombstone_ttl_ms,
+--       JSON object of meta fields (string -> string),
+--       JSON array of unit ids (success mode only),
+--       unit type (optional, default "file")
+--
+-- Aborts with a Lua error (mapped by Ruby) when the caller no longer holds the
+-- lease (LEASE_LOST), the tombstone exists (ALREADY_INITIALIZED) or meta is
+-- already published (ALREADY_READY). Returns "ready" or "init_failed".
+
+local units, priority, attempts, meta, unit_state, leader, exists =
+  KEYS[1], KEYS[2], KEYS[3], KEYS[4], KEYS[5], KEYS[6], KEYS[7]
+local mode, token = ARGV[1], ARGV[2]
+local ttl_ms, tombstone_ttl_ms = tonumber(ARGV[3]), tonumber(ARGV[4])
+local unit_type = ARGV[7] or "file"
+
+local GROUP = "workers"
+local INITIAL_UNIT_STATE = '{"retry_index":0,"reclaim_count":0,"entered_retry":false}'
+
+local function now_ms()
+  local t = redis.call("TIME")
+  return tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+end
+
+local function fence()
+  if redis.call("GET", leader) ~= token then
+    return redis.error_reply("LEASE_LOST")
+  end
+  if redis.call("EXISTS", exists) == 1 then
+    return redis.error_reply("ALREADY_INITIALIZED")
+  end
+  if redis.call("EXISTS", meta) == 1 then
+    return redis.error_reply("ALREADY_READY")
+  end
+  return nil
+end
+
+local function write_meta(fields, extra)
+  local args = {}
+  for k, v in pairs(fields) do
+    args[#args + 1] = k
+    args[#args + 1] = tostring(v)
+  end
+  for k, v in pairs(extra) do
+    args[#args + 1] = k
+    args[#args + 1] = tostring(v)
+  end
+  redis.call("HSET", meta, unpack(args))
+end
+
+local function seed_units(unit_ids)
+  redis.call("DEL", units, priority)
+  redis.call("XGROUP", "CREATE", units, GROUP, "0", "MKSTREAM")
+  redis.call("XGROUP", "CREATE", priority, GROUP, "0", "MKSTREAM")
+  for _, id in ipairs(unit_ids) do
+    redis.call("XADD", units, "*", "id", id, "type", unit_type)
+    redis.call("HSET", unit_state, id, INITIAL_UNIT_STATE)
+  end
+end
+
+local function set_ttls()
+  redis.call("SET", exists, "1", "PX", tombstone_ttl_ms)
+  for _, key in ipairs({ units, priority, attempts, meta, unit_state }) do
+    redis.call("PEXPIRE", key, ttl_ms)
+  end
+end
+
+local function init_success(fields, unit_ids)
+  seed_units(unit_ids)
+  write_meta(fields, { state = "ready", ready_at = now_ms(), finalized_count = 0, requeued_units_count = 0 })
+  set_ttls()
+  return "ready"
+end
+
+local function init_failure(fields)
+  write_meta(fields, { state = "init_failed", ready_at = now_ms() })
+  set_ttls()
+  return "init_failed"
+end
+
+local aborted = fence()
+if aborted then
+  return aborted
+end
+
+local fields = cjson.decode(ARGV[5])
+if mode == "success" then
+  return init_success(fields, cjson.decode(ARGV[6]))
+elseif mode == "failure" then
+  return init_failure(fields)
+end
+return redis.error_reply("ERR unknown init mode " .. tostring(mode))