bitfab 0.21.2 → 0.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 910352d2c5434b3fae7c3c56ccfea74dc0a22ce35d0cb4d2cb9d463e4ba3660b
-  data.tar.gz: 2e4e07a7447b75404e753f9a2d45350edfbee088ba100aff06031cf477cbc59c
+  metadata.gz: eb8d7ab7e95fed00c067b1653c4d8271c1814b6a9d42bc8ffbb320596ac2190e
+  data.tar.gz: 6050620ec20d4172045e7a7c29930349e488cd886132cb54758ca98d789be34f
 SHA512:
-  metadata.gz: 1d197beb80ef3dcd1e57a8aebbe3aafd39ed000cadb0e1098ca71369d69ba53d4e805626f632b3bfdfb5f0cbe36d12e34d589f0b3def09be7e397bb1363e8b5e
-  data.tar.gz: 2f35b7eeba42eb86005e8cb9af3f46654313a84bc375e3c0edbd04e716cd8c511d0d302c2626d5f679b663f3482a24d8ec9b91d9b653fb2da6412aea0da2280b
+  metadata.gz: c94a534717dfbf682ca6d4f1fb6e9501fba8df1057bd6390457c4f561616a23bf53092bfc4bc8cc966f67037d1a7a9b8f2eadc4edff92645a99e2b0a9ffcf33b
+  data.tar.gz: 7e416c3b5af6248ada3bda42d56d2853d68792e7adcf3bb4a1e1af98b5b4740ee92cd7e25ba8c86fee0bc0b0acaa5acd102bb1d8e561d03d0e669d24de877048

data/lib/bitfab/client.rb

@@ -68,11 +68,11 @@ module Bitfab
     #   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,
-      code_change_description: nil, code_change_files: nil, experiment_group_id: nil, dataset_id: nil, mock: "none",
+      name: nil, code_change_description: nil, code_change_files: nil, experiment_group_id: nil, dataset_id: nil, mock: "none",
       adapt_inputs: nil, environment: nil, on_progress: nil)
       Replay.run(
         self, receiver, method_name,
-        trace_function_key:, limit:, trace_ids:, max_concurrency:,
+        trace_function_key:, limit:, trace_ids:, name:, max_concurrency:,
         code_change_description:, code_change_files:, experiment_group_id:, dataset_id:, mock:, adapt_inputs:, environment:,
         on_progress:
       )

data/lib/bitfab/constants.rb

@@ -3,4 +3,8 @@
 module Bitfab
   DEFAULT_SERVICE_URL = "https://bitfab.ai"
   REPLAY_CONTEXT_KEY = :__bitfab_replay_context
+
+  # Wire prefix the Bitfab plugin scans for on stderr to report live progress
+  # while a replay runs. One trailing space, then the progress object as JSON.
+  BITFAB_PROGRESS_PREFIX = "@@bitfab:progress "
 end

data/lib/bitfab/http_client.rb

@@ -107,10 +107,12 @@ module Bitfab
     #   each as { path:, before:, after: } (use "" for new/deleted files)
     # @param experiment_group_id [String, nil] optional UUID grouping multiple
     #   replay runs into a single experiment batch
+    # @param name [String, nil] optional display name for the resulting
+    #   experiment/test run
     # @param dataset_id [String, nil] optional UUID of the dataset this replay
     #   runs against, stored on the resulting experiment for durable attribution
     def start_replay(trace_function_key, limit, trace_ids: nil, code_change_description: nil,
-      code_change_files: nil, experiment_group_id: nil, include_db_branch_lease: false, dataset_id: nil)
+      code_change_files: nil, experiment_group_id: nil, name: nil, include_db_branch_lease: false, dataset_id: nil)
       payload = {
         "traceFunctionKey" => trace_function_key
       }
@@ -118,6 +120,7 @@ module Bitfab
       # already determines the count), so it's omitted when nil.
       payload["limit"] = limit unless limit.nil?
       payload["traceIds"] = trace_ids if trace_ids
+      payload["name"] = name unless name.nil?
       payload["codeChangeDescription"] = code_change_description unless code_change_description.nil?
       payload["codeChangeFiles"] = normalize_code_change_files(code_change_files) unless code_change_files.nil?
       payload["experimentGroupId"] = experiment_group_id unless experiment_group_id.nil?

data/lib/bitfab/replay.rb

@@ -82,6 +82,7 @@ module Bitfab
     #   Ignored when trace_ids is passed (with a warning): an explicit ID list
     #   already determines how many traces replay.
     # @param trace_ids [Array<String>, nil] optional list of trace IDs to replay (max 100)
+    # @param name [String, nil] optional display name for the resulting experiment/test run
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
     # @param code_change_description [String, nil] optional rationale for the
     #   code change being tested in this replay (stored on the experiment)
@@ -102,11 +103,16 @@ module Bitfab
     #   that item's :error rather than crashing the run.
     # @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). A raising callback never crashes the run.
+    #   errored:, item: } where item is { trace_id:, error:, duration_ms: } for
+    #   the single item that just settled. trace_id is the SOURCE (historical)
+    #   trace that was replayed, error is that item's replay error or nil, and
+    #   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.
     # @return [Hash] with :items, :test_run_id, :test_run_url
-    def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, max_concurrency: 10,
-      code_change_description: nil, code_change_files: nil, experiment_group_id: nil, dataset_id: nil, mock: "none",
+    def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil,
+      max_concurrency: 10, code_change_description: nil, code_change_files: nil, experiment_group_id: nil,
+      dataset_id: nil, mock: "none",
       adapt_inputs: nil, environment: nil, on_progress: nil)
       unless MOCK_STRATEGIES.include?(mock.to_s)
         raise ArgumentError, "Invalid mock strategy '#{mock}'. Must be one of: #{MOCK_STRATEGIES.join(", ")}"
@@ -149,6 +155,7 @@ module Bitfab
         trace_function_key,
         effective_limit,
         trace_ids:,
+        name:,
         code_change_description:,
         code_change_files:,
         experiment_group_id:,
@@ -254,14 +261,23 @@ module Bitfab
       completed = 0
       succeeded = 0
       errored = 0
-      report = lambda do |result|
+      # Each event carries the single item that just settled so a progress UI
+      # can render per-trace pass/fail as the run streams. trace_id is the
+      # SOURCE (historical) trace that was replayed, taken from the server
+      # item: the result's own :trace_id at this stage is the new replay
+      # trace id (assigned in run() after complete_replay), not the source.
+      report = lambda do |result, source_trace_id|
         return unless on_progress
 
         progress_mutex.synchronize do
           completed += 1
-          result[:error].nil? ? (succeeded += 1) : (errored += 1)
+          error = result[:error]
+          error.nil? ? (succeeded += 1) : (errored += 1)
           begin
-            on_progress.call({completed:, total:, succeeded:, errored:})
+            on_progress.call({
+              completed:, total:, succeeded:, errored:,
+              item: {trace_id: source_trace_id, error:, duration_ms: result[:duration_ms]}
+            })
           rescue => e
             warn "Bitfab: replay on_progress callback raised: #{e.message}"
           end
@@ -272,7 +288,7 @@ module Bitfab
         server_items.map do |item|
           result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
             adapt_inputs, include_db_branch_lease)
-          report.call(result)
+          report.call(result, item["traceId"])
           result
         end
       else
@@ -290,7 +306,7 @@ module Bitfab
               result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
                 adapt_inputs, include_db_branch_lease)
               results_mutex.synchronize { results[idx] = result }
-              report.call(result)
+              report.call(result, item["traceId"])
             end
           end
         end

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 require_relative "bitfab/version"
 require_relative "bitfab/constants"
 require_relative "bitfab/warn_once"
@@ -103,5 +105,26 @@ 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 ({ trace_id:,
+    # error:, duration_ms: }) is forwarded verbatim through to_json, so the
+    # plugin sees the source trace id, error, and duration of the item that just
+    # settled.
+    #
+    # @example
+    #   Bitfab.client.replay(..., on_progress: Bitfab.method(:report_replay_progress))
+    #
+    # @param progress [Hash] running totals with keys completed, total,
+    #   succeeded, errored, and item (the object replay already passes to
+    #   on_progress)
+    def report_replay_progress(progress)
+      warn "#{BITFAB_PROGRESS_PREFIX}#{progress.to_json}"
+    rescue
+      nil
+    end
   end
 end

metadata

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