bitfab 0.36.3 → 0.36.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: deea3052760a7b677216225f0cd030f4931995b1d10e6b7396c97a57a27ab9c1
-  data.tar.gz: 5f64a512db5c8c79f092e5bbf92e16adfc2e20a4a07c869eafab48fb42db5665
+  metadata.gz: 5578e8fdcdd81610b4e65fa94a5e9be88339e816742f6ba7fea81b53867eedf5
+  data.tar.gz: 308d35969ac643d1ddcfb76c169a6108906c958275b392f7d159ea647b0bf63c
 SHA512:
-  metadata.gz: f9024ab4975b3963e4d2c91aa903b3e4bc7880791aa1f0a4132a9ee847e54e2132339246cbc1067beba8a2130e813738474fcc40a38a1d3b9a0e19ba92633834
-  data.tar.gz: b3c4b7c252a566192362e6d1a3e4d31bcad55f752a70527fce5de87ebc9ab75c4839a02fd5d67589823ee36003f3fcb49d5bdade0a315dc8a22971b9769ea9c3
+  metadata.gz: 2c0511909223595a7792e780d0c77b8c0f5ef2d239e4b2a5dda7946a63fbe4801893ae02ba3392b74520ad9d82844e519d3319a900f22c30bef4857e616c0420
+  data.tar.gz: 0ae83e2f731bc2f6fa9f564b6fe8754b7fff82c5ae03a914067cca6fb75f4ddb10e935bba8976de6f0dabe7025812e49d9392e2ace61b5202c02d80b21fe00aa

data/lib/bitfab/client.rb

@@ -132,21 +132,27 @@ module Bitfab
     #   +:min_cu+/+:max_cu+ size the branch compute in Neon Compute Units and
     #   +:warmup_sql+ warms its cache. Read the resolved branch inside the
     #   replayed method with +Bitfab.current_replay_branch+.
-    # @param on_progress [#call, nil] optional callback invoked once per item as
-    #   it finishes, with a running-totals hash { completed:, total:, succeeded:,
-    #   errored: }. Use it to render replay progress (e.g. a terminal progress
-    #   bar). Replay does not know pass/fail yet, so the totals only distinguish
-    #   items whose method ran (:succeeded) from items that raised (:errored).
-    #   A raising callback never crashes the run.
+    # @param on_item_finish [#call, nil] optional callback invoked exactly once
+    #   per item as it finishes, always with a running-totals hash containing
+    #   { completed:, total:, succeeded:, errored:, item: }. It never receives a
+    #   whole-run completion event. Replay does not know pass/fail yet, so the
+    #   totals only distinguish items whose method ran (:succeeded) from items
+    #   that raised (:errored). A raising callback never crashes the run.
+    # @param on_progress [#call, nil] deprecated compatibility callback. It
+    #   receives the same per-item events plus the legacy item-less +"complete"+
+    #   event. Ignored when +on_item_finish+ is also provided.
+    # @param on_item_start [#call, nil] optional callback invoked when a worker
+    #   begins processing each item. Pair it with on_item_finish to distinguish
+    #   queued work from in-flight work. A raising callback never crashes the run.
     # @return [Hash] with :items, :test_run_id, :test_run_url
     def replay(receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, max_concurrency: 10,
       name: nil, code_change_description: Replay::CODE_CHANGE_UNSET, code_change_files: Replay::CODE_CHANGE_UNSET, experiment_group_id: nil, dataset_id: nil, grader_ids: nil, mock: "marked",
-      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil)
       Replay.run(
         self, receiver, method_name,
         trace_function_key:, limit:, trace_ids:, name:, max_concurrency:,
         code_change_description:, code_change_files:, experiment_group_id:, dataset_id:, grader_ids:, mock:, adapt_inputs:,
-        mock_override:, db_branch:,
+        mock_override:, db_branch:, on_item_start:, on_item_finish:,
         on_progress:
       )
     end

data/lib/bitfab/replay.rb

@@ -201,11 +201,11 @@ module Bitfab
     #   and ceiling in Neon Compute Units, and +:warmup_sql+ warms the branch's
     #   cache before the replayed method sees it. Read the resolved branch
     #   inside the method with +Bitfab.current_replay_branch+.
-    # @param on_progress [#call, nil] optional callback invoked once per item as
+    # @param on_item_finish [#call, nil] optional callback invoked once per item as
     #   it finishes, with a running-totals hash { completed:, total:, succeeded:,
     #   errored:, item: } where item is { trace_id:, original_trace_id:,
     #   original_span_id:, error:, duration_ms: } for the single item that just
-    #   settled (source_trace_id/source_span_id remain as deprecated aliases).
+    #   finished (source_trace_id/source_span_id remain as deprecated aliases).
     #   trace_id is the new server replay trace id, written in after the run
     #   completes (nil during progress callbacks); original_trace_id is the
     #   ORIGINAL (historical) trace that was replayed, error is that item's replay
@@ -213,14 +213,22 @@ module Bitfab
     #   duration_ms is how long that one trace took to replay. Use it to
     #   render replay progress (e.g. a per-trace log). A raising callback never
     #   crashes the run.
+    # @param on_progress [#call, nil] deprecated compatibility callback. It
+    #   receives the same per-item finish events plus the legacy whole-run
+    #   +"complete"+ event. Ignored when +on_item_finish+ is also provided.
+    # @param on_item_start [#call, nil] optional callback invoked when a worker
+    #   begins processing each item, before replay setup and customer code run.
+    #   Pair it with on_item_finish to distinguish queued work from in-flight work.
+    #   A raising callback never crashes the run.
     # @return [Hash] with :items, :test_run_id, :test_run_url
     def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil,
       max_concurrency: 10, code_change_description: CODE_CHANGE_UNSET, code_change_files: CODE_CHANGE_UNSET, experiment_group_id: nil,
       dataset_id: nil, grader_ids: nil, mock: "marked",
-      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil)
       unless MOCK_STRATEGIES.include?(mock.to_s)
         raise ArgumentError, "Invalid mock strategy '#{mock}'. Must be one of: #{MOCK_STRATEGIES.join(", ")}"
       end
+      item_finish_callback = on_item_finish || on_progress
       if trace_ids
         raise ArgumentError, "trace_ids must contain at least one trace ID." if trace_ids.empty?
         if trace_ids.length > 100
@@ -296,7 +304,8 @@ module Bitfab
 
       result_items = if server_items.any?
         process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock.to_s,
-          adapt_inputs, include_db_branch_lease, resolved_db_branch_settings, on_progress:,
+          adapt_inputs, include_db_branch_lease, resolved_db_branch_settings, on_item_start:,
+          on_item_finish: item_finish_callback,
           mock_overrides: resolved_overrides)
       else
         []
@@ -383,14 +392,12 @@ module Bitfab
         test_run_id:,
         test_run_url: full_test_run_url
       }
-      # Persist the enriched result two ways so the Bitfab plugin never has to
-      # parse the replay's stdout (which a dependency's logging can corrupt):
-      # write it to BITFAB_REPLAY_RESULT_PATH when the plugin set that env var,
-      # and stream a terminal "complete" progress event. The plugin prefers the
-      # streamed event and falls back to the file. The event routes through
-      # on_progress so only progress-reporting runs emit it.
+      # Persist the enriched result so the Bitfab plugin never has to parse the
+      # replay's stdout, which a dependency's logging can corrupt.
       write_replay_result_file(result)
-      if on_progress
+      # Preserve the legacy terminal event only for on_progress. on_item_finish
+      # is strictly item-scoped, so every invocation always includes an item.
+      if on_item_finish.nil? && on_progress
         errored = result_items.count { |item| !item[:error].nil? }
         total = result_items.length
         begin
@@ -631,36 +638,56 @@ module Bitfab
 
     # Process all replay items, optionally in parallel using threads.
     def process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock_strategy,
-      adapt_inputs = nil, include_db_branch_lease = false, db_branch_settings = nil, on_progress: nil,
+      adapt_inputs = nil, include_db_branch_lease = false, db_branch_settings = nil, on_item_start: nil, on_item_finish: nil,
       mock_overrides: [])
       concurrency = max_concurrency || server_items.length
 
-      # Reports running totals once per item as it settles. In the parallel
-      # path it runs from worker threads, so the mutex both makes the counter
-      # updates safe and serializes the user's callback (never called
-      # concurrently). A raising callback is swallowed: progress UI must never
-      # crash the run.
+      # Lifecycle callbacks run from worker threads in the parallel path, so the
+      # mutex makes counter updates safe and serializes each callback. A raising
+      # callback is swallowed because progress UI must never crash the run.
       total = server_items.length
       progress_mutex = Mutex.new
+      started = 0
       completed = 0
       succeeded = 0
       errored = 0
-      # Each event carries the single item that just settled so a progress UI
+      # Each event carries the single item that just finished so a progress UI
       # can render per-trace pass/fail as the run streams. The item's :trace_id
       # is nil at this stage: the server replay trace id isn't known until run()
       # writes it in after complete_replay, and the client correlation id is
       # never surfaced. original_trace_id (the historical trace being replayed,
       # taken from the server item) is what a UI keys on to identify what just
-      # settled. source_trace_id/source_span_id are kept as deprecated aliases.
-      report = lambda do |result, original_trace_id, original_span_id, test_run_id|
-        return unless on_progress
+      # finished. source_trace_id/source_span_id are kept as deprecated aliases.
+      report_start = lambda do |original_trace_id, original_span_id|
+        progress_mutex.synchronize do
+          started += 1
+          next unless on_item_start
+
+          begin
+            on_item_start.call({
+              type: "started", test_run_id:, started:, completed:, total:, succeeded:, errored:,
+              item: {
+                original_trace_id:,
+                original_span_id:,
+                source_trace_id: original_trace_id,
+                source_span_id: original_span_id
+              }
+            })
+          rescue => e
+            warn "Bitfab: replay on_item_start callback raised: #{e.message}"
+          end
+        end
+      end
 
+      report = lambda do |result, original_trace_id, original_span_id, test_run_id|
         progress_mutex.synchronize do
           completed += 1
           error = result[:error]
           error.nil? ? (succeeded += 1) : (errored += 1)
+          next unless on_item_finish
+
           begin
-            on_progress.call({
+            on_item_finish.call({
               test_run_id:, completed:, total:, succeeded:, errored:,
               item: {
                 trace_id: result[:trace_id],
@@ -682,13 +709,14 @@ module Bitfab
               }
             })
           rescue => e
-            warn "Bitfab: replay on_progress callback raised: #{e.message}"
+            warn "Bitfab: replay on_item_finish callback raised: #{e.message}"
           end
         end
       end
 
       if concurrency <= 1
         server_items.map do |item|
+          report_start.call(original_trace_id_of(item), original_span_id_of(item))
           result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
             adapt_inputs, include_db_branch_lease, db_branch_settings, mock_overrides:)
           report.call(result, original_trace_id_of(item), original_span_id_of(item), test_run_id)
@@ -706,6 +734,7 @@ module Bitfab
               item, idx = work_mutex.synchronize { work_queue.shift }
               break unless item
 
+              report_start.call(original_trace_id_of(item), original_span_id_of(item))
               result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
                 adapt_inputs, include_db_branch_lease, db_branch_settings, mock_overrides:)
               results_mutex.synchronize { results[idx] = result }

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.36.3"
+  VERSION = "0.36.4"
 end

data/lib/bitfab.rb

@@ -144,20 +144,18 @@ module Bitfab
       CurrentTrace.new(entry[:trace_id])
     end
 
-    # A ready-made on_progress callback for replay: writes one @@bitfab:progress
-    # line per trace to stderr, which the Bitfab plugin polls to report live
-    # progress while the replay runs in the background, so replay scripts never
-    # hand-format the protocol. stdout stays the ReplayResult JSON. Never raises
-    # (progress must not crash a run). The progress hash's item is forwarded
-    # verbatim through to_json, so the plugin sees the source trace id, local
-    # replay trace id, outputs, error, and duration of the item that just settled.
+    # A ready-made replay lifecycle reporter. Pass it as both on_item_start and
+    # on_item_finish so the Bitfab plugin sees in-flight and finished items. It writes
+    # @@bitfab:progress lines to stderr, leaving stdout for ReplayResult JSON, and
+    # never raises because progress reporting must not crash a run.
     #
     # @example
-    #   Bitfab.client.replay(..., on_progress: Bitfab.method(:report_replay_progress))
+    #   reporter = Bitfab.method(:report_replay_progress)
+    #   Bitfab.client.replay(..., on_item_start: reporter, on_item_finish: reporter)
     #
     # @param progress [Hash] running totals with keys completed, total,
     #   succeeded, errored, and item (the object replay already passes to
-    #   on_progress)
+    #   on_item_finish)
     def report_replay_progress(progress)
       warn "#{BITFAB_PROGRESS_PREFIX}#{Replay.json_safe(progress).to_json}"
     rescue

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.36.3
+  version: 0.36.4
 platform: ruby
 authors:
 - Harvest Team