rspec-tracer 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd23aee4693655e787948be6a1e049f99942f8bf0b7f763dd7b2df9f04a01eec
-  data.tar.gz: a88e6daf316e8f35fecb6661a08c837470c7f0e3396d5e63522c29614e975d6e
+  metadata.gz: 24ed84e70e415d8eccd09ea63cee04cc318e4a167227dc9f937a3badb7229fb6
+  data.tar.gz: fa6d30e91e776b35b935b5e0e420422700d552859d894d001e16fee2b93e0874
 SHA512:
-  metadata.gz: f9ab2ad270d188230c5d6eb82593055151dcb1f0d43d2c15fb15bab5d96876d8cae12f70c75eff7c80e81c6c53d8930812c173b5e67899f007237170b66deb9a
-  data.tar.gz: 9d3ce6ded81c0ce02a6a294d1317a732890ef3814a443e87c5345c65e316463e9266af701fe03520283cf58e1e7ecf9165d5ad45aa224e4f46f5410b0790394a
+  metadata.gz: 4c3abb2234b5c02257f70c494775a4d01d5fe84dfeb9d61eba92f70064a649045607ac801b526ca8198b3defc75db8751db68597557ae379666f0c979236cbe0
+  data.tar.gz: 23b9a629e8a8d93af51d74b2d426c6770db64ed9971c50fb269f96dd74abcb1badc520f02289725d96a97a7e5077210e6d54e3405da2510a799a4ec956cd81c9

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [1.0.4] - 2026-05-06
+
+### Fixed
+
+- **Parallel-tests purge race when a sibling worker is still mid-flush**
+  — the elected worker trusted only `parallel_tests`'s pid-file barrier
+  (`ParallelTests.wait_for_other_processes_to_finish`), which under
+  specific scheduling/I/O timing on GHA Linux x86_64 can return while a
+  sibling's `parallel_tests_N/` dir hasn't fully flushed. The elected
+  then merged + purged, racing the in-progress sibling. Symptoms:
+  intermittent leftover `parallel_tests_N/` dir post-purge AND/OR
+  silently dropped peer caches in the merge.
+
+  Backport of upstream PR
+  [#168](https://github.com/avmnu-sng/rspec-tracer/pull/168). Adds a
+  filesystem barrier layered on top of the pid-file wait. Each worker
+  writes a `.rspec_tracer_boot` marker at `RSpecTracer.start` time and
+  a `.rspec_tracer_done` marker as the first step of its at_exit tasks;
+  the elected worker waits for every booted peer's `.done` to
+  materialize before proceeding to merge + purge. Two independent
+  signals (pid file + filesystem) must agree before the elected worker
+  declares the peer set stable. Bounded at 5 s with a graceful warn
+  for crashed peers — their dirs are purged regardless of completion
+  state, and the merge accepts whatever's on disk.
+
 ## [1.0.3] - 2026-05-04
 
 ### Fixed

data/lib/rspec_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RSpecTracer
-  VERSION = '1.0.3'
+  VERSION = '1.0.4'
 end

data/lib/rspec_tracer.rb

@@ -32,6 +32,17 @@ require_relative 'rspec_tracer/time_formatter'
 require_relative 'rspec_tracer/version'
 
 module RSpecTracer
+  # Filesystem barrier markers, layered on top of parallel_tests's
+  # pid-file wait to defend against the GHA-observed race where the
+  # gem's `wait_for_other_processes_to_finish` returns while a sibling
+  # worker hasn't fully flushed its `parallel_tests_N/` dir yet. Each
+  # worker writes BOOT at setup-time and DONE as the first step of its
+  # at_exit tasks; the elected worker waits for every booted peer's
+  # DONE marker (deadline-bounded) before proceeding to merge + purge.
+  PARALLEL_TESTS_BOOT_MARKER_FILENAME = '.rspec_tracer_boot'
+  PARALLEL_TESTS_DONE_MARKER_FILENAME = '.rspec_tracer_done'
+  PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS = 5
+
   class << self
     attr_accessor :running, :pid, :no_examples
 
@@ -191,6 +202,27 @@ module RSpecTracer
       puts "Failed to load parallel tests (Error: #{e.message})"
     ensure
       track_parallel_tests_test_env_number
+      parallel_tests_touch_boot!
+    end
+
+    # Per-worker boot marker. Source-of-truth for "this worker booted
+    # past `RSpecTracer.start`", consumed by the elected worker's
+    # finalize-time peer enumeration. Idempotent; failures are warned
+    # and absorbed (boot-marker write must never block test execution).
+    def parallel_tests_touch_boot!
+      return unless parallel_tests?
+
+      FileUtils.mkdir_p(RSpecTracer.cache_path)
+      File.write(
+        File.join(RSpecTracer.cache_path, PARALLEL_TESTS_BOOT_MARKER_FILENAME),
+        JSON.generate(
+          pid: Process.pid,
+          test_env_number: ENV.fetch('TEST_ENV_NUMBER', ''),
+          started_at: Time.now.utc.iso8601
+        )
+      )
+    rescue StandardError => e
+      puts "RSpec tracer: failed to write boot marker (#{e.class}: #{e.message})"
     end
 
     def track_parallel_tests_test_env_number
@@ -324,6 +356,15 @@ module RSpecTracer
     end
 
     def run_parallel_tests_exit_tasks
+      # Every worker — elected or not — drops its `.done` marker as the
+      # first thing in finalize so the elected worker's
+      # `parallel_tests_wait_for_peer_done_markers!` can observe it.
+      # Non-elected workers stop here; the elected worker proceeds to
+      # the merge + purge sequence (gated by `parallel_tests_executed?`,
+      # which now layers the peer-done barrier on top of the existing
+      # pid-file wait).
+      parallel_tests_touch_done!
+
       return unless parallel_tests_executed?
 
       merge_parallel_tests_reports
@@ -333,6 +374,24 @@ module RSpecTracer
       purge_parallel_tests_reports
     end
 
+    # Per-worker done marker. Written by every worker (elected or not)
+    # as the first step of `run_parallel_tests_exit_tasks`. Pairs with
+    # the boot marker for the elected worker's peer-done barrier:
+    # presence of `.done` means "this worker has signalled completion
+    # of its own writes"; absence (with `.boot` present) means "still
+    # mid-flush or crashed". Idempotent; failures are warned + absorbed.
+    def parallel_tests_touch_done!
+      return unless parallel_tests?
+
+      FileUtils.mkdir_p(RSpecTracer.cache_path)
+      File.write(
+        File.join(RSpecTracer.cache_path, PARALLEL_TESTS_DONE_MARKER_FILENAME),
+        Time.now.utc.iso8601
+      )
+    rescue StandardError => e
+      puts "RSpec tracer: failed to write done marker (#{e.class}: #{e.message})"
+    end
+
     def merge_parallel_tests_reports
       return unless parallel_tests_executed?
 
@@ -432,9 +491,62 @@ module RSpecTracer
 
       ParallelTests.wait_for_other_processes_to_finish
 
+      # Belt-and-suspenders barrier: pid-file said everyone's done, but
+      # the gem's `wait_for_other_processes_to_finish` has been observed
+      # on GHA Linux x86_64 to return while a sibling's `parallel_tests_N/`
+      # is still mid-flush. Cross-check via the `.boot`/`.done` filesystem
+      # markers before declaring the peer set stable. Idempotent: once
+      # all peers have flushed, subsequent calls just glob, find nothing
+      # missing, and return.
+      parallel_tests_wait_for_peer_done_markers!
+
       true
     end
 
+    # Block until every peer that wrote `.boot` has also written `.done`,
+    # or the deadline elapses. Polled at 50ms — fine enough to close the
+    # typical "barrier returned a tick early" case within a poll or two,
+    # coarse enough not to dominate CPU.
+    #
+    # On timeout we log and proceed: a peer that never wrote `.done`
+    # either crashed (then its dir is orphan content; the subsequent
+    # purge cleans it) or is genuinely hung (the elected can't fix that
+    # — we choose merge correctness over indefinite wait).
+    def parallel_tests_wait_for_peer_done_markers!
+      base_dir = File.dirname(RSpecTracer.cache_path)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS
+
+      loop do
+        missing = parallel_tests_peer_dirs_missing_done(base_dir)
+        return if missing.empty?
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          puts 'RSpec tracer: peers booted without finishing within ' \
+               "#{PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS}s: #{missing.inspect}; " \
+               'proceeding (peer dirs will be purged regardless of completion state)'
+          return
+        end
+
+        sleep 0.05
+      end
+    end
+
+    # Set difference of `.boot`-bearing peer dirs and `.done`-bearing
+    # peer dirs under `base_dir`. A returned entry means "this peer
+    # registered but has not signalled completion yet" — either still
+    # mid-flush or crashed.
+    def parallel_tests_peer_dirs_missing_done(base_dir)
+      boot_dirs = parallel_tests_peer_dirs_with_marker(base_dir, PARALLEL_TESTS_BOOT_MARKER_FILENAME)
+      done_dirs = parallel_tests_peer_dirs_with_marker(base_dir, PARALLEL_TESTS_DONE_MARKER_FILENAME)
+      boot_dirs - done_dirs
+    end
+
+    def parallel_tests_peer_dirs_with_marker(base_dir, marker_filename)
+      Dir.glob(File.join(base_dir, 'parallel_tests_*', marker_filename)).map do |path|
+        File.dirname(path)
+      end
+    end
+
     # Elects the worker that performs the per-run merge. Delegates to
     # `::ParallelTests.first_process?`, which returns true iff
     # `TEST_ENV_NUMBER.to_i <= 1` — i.e. for exactly one worker per run,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-tracer
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - Abhimanyu Singh
@@ -118,7 +118,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/avmnu-sng/rspec-tracer
-  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.0.3
+  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.0.4
   changelog_uri: https://github.com/avmnu-sng/rspec-tracer/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/avmnu-sng/rspec-tracer/issues
 rdoc_options: []