rspec-tracer 1.2.2 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f6c19e285b64650bd4f02c5820fed75c10806ebb97900e17607b84532dfb483
-  data.tar.gz: a4e17229c1efa3d43e1cc850b908cb9bbcb16fb6f217098348675ce2a798c993
+  metadata.gz: 1c0ed3fbdb4a082d56a4d83a528dff26bd174abeb28cf1669dc5dd79de521cee
+  data.tar.gz: ebc2fbdfde4c6ac82072b5464f5dc0441d73efd24b4410ed96d3892ea765f1a9
 SHA512:
-  metadata.gz: 25571686f98b2c1939a0497f3c34a7f0508d856ba94ac2aabd6f293815a4e61ad8cb2b56d8a22c4ff211692a6609c1f8671d6b55f35d2123301d15bf8d70649b
-  data.tar.gz: 1c86b20818bc6f18bc5a3faf69f6a7b7908b1ab6006a1301341883edb46f3d180db3cd6308978f9d12dbd6f9b427dcd478c3addc7888f78faa64dc1b325897ce
+  metadata.gz: 1c28a6a997cf74dbb8d910972d9dd8e0b6e9f36aaacc9670e8a50a6bf7c0d4100f6cf421befcba8349750c3ba179a05b86d2a0cbdf740280d490d4bd42c37512
+  data.tar.gz: ce834032d235ea1e2775fb127ac040d6f12f560e7cf9babe5fd208a68cb5dd7260a2ac1f2af78b2a782a622902d9b8291adb2ca339837de70b9f12259e05a456

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [1.2.3] - 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.2.2] - 2026-05-04
 
 ### Fixed

data/lib/rspec_tracer/version.rb

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

data/lib/rspec_tracer.rb

@@ -30,6 +30,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, :duplicate_examples
 
@@ -186,6 +197,29 @@ module RSpecTracer
       RSpecTracer.logger.error "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
+      RSpecTracer.logger.warn(
+        "RSpec tracer: failed to write boot marker (#{e.class}: #{e.message})"
+      )
     end
 
     def track_parallel_tests_test_env_number
@@ -315,6 +349,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
@@ -324,6 +367,26 @@ 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
+      RSpecTracer.logger.warn(
+        "RSpec tracer: failed to write done marker (#{e.class}: #{e.message})"
+      )
+    end
+
     def merge_parallel_tests_reports
       return unless parallel_tests_executed?
 
@@ -423,9 +486,64 @@ 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 a warn 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
+          RSpecTracer.logger.warn(
+            '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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-tracer
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.3
 platform: ruby
 authors:
 - Abhimanyu Singh
@@ -111,7 +111,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.2.2
+  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.2.3
   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: []