bitfab 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6264d16b3fdf093418d97c43141db5a83e890d0b5e8993f255498c01548c31b
-  data.tar.gz: 158be7664defce737b4b6e3a1db39f6bf13fee37aee9f9948fb63f7b2dd2a254
+  metadata.gz: 3320e43b6f1be704f5ab955161b347d954691c6cdc75f5e57ab01452e8f8dd7f
+  data.tar.gz: 2b8872ef106d63560d6718ab4d2076f6271417fbc56e44581c2e4f5058ff4a00
 SHA512:
-  metadata.gz: cb6a19c8fcfd500c58e0bbf7a1332fb27b6701282cc859bf2590477bae8fd4aaf871e37e15fc9eb0f70cbe7c121b5550f1d7ce536d771992282e0484eb545d1e
-  data.tar.gz: b6ab4f9aa78b82b8a14d993e1357ae9db9fd09447a16ea8e5ff301998504548f7d54339923f238e4065661fcc61e8ae3db2171a8b4c00f30b1695d20f87d7546
+  metadata.gz: f9599b68cfbac6812070bfd05516b1372e607e5cc2214a5e7319ca39b5e22c80390db4b3446e6c136bea2c2a0780e8ffeab5fbb99226e2bf7636ace35a9a72f5
+  data.tar.gz: 98c9855c1d5f3cb4403926820b223733c555696211ab27d0980c06f9f38e01aa02b0e4c2065525c33eed6bd8e60f0136b3a4951a67416051181287b5f7acbc7a

data/lib/bitfab/client.rb

@@ -53,13 +53,18 @@ module Bitfab
     # @param mock [String] mock strategy for child spans: "none" (default),
     #   "all", or "marked". "all" mocks every child span; "marked" only mocks
     #   spans declared with mock_on_replay: true.
+    # @param adapt_inputs [#call, nil] optional hook to reshape recorded inputs
+    #   onto the method's current signature when its shape changed after the
+    #   traces were captured. Receives (args, kwargs, ctx) where ctx is
+    #   { trace_id:, source_span_id: }, and returns [new_args, new_kwargs].
     # @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, mock: "none")
+      code_change_description: nil, code_change_files: nil, experiment_group_id: nil, mock: "none",
+      adapt_inputs: nil)
       Replay.run(
         self, receiver, method_name,
         trace_function_key:, limit:, trace_ids:, max_concurrency:,
-        code_change_description:, code_change_files:, experiment_group_id:, mock:
+        code_change_description:, code_change_files:, experiment_group_id:, mock:, adapt_inputs:
       )
     end
 
@@ -183,12 +188,24 @@ module Bitfab
             pending << span_thread if span_thread
             pending.each { |t| t.join(5) }
 
-            send_trace_completion(
+            completion_thread = send_trace_completion(
               trace_function_key:,
               trace_id:,
               started_at:,
               ended_at:
             )
+
+            # In replay, persistence is correctness: the replay runner joins
+            # these threads before calling complete_replay, or the server's
+            # trace-ID mapping races the uploads and every item's trace_id
+            # comes back nil. The 5s join above is best-effort only; this
+            # hands the full set (span uploads + trace completion) to the
+            # runner. No-op outside replay, where sends stay fire-and-forget.
+            persistence = ReplayContext.current&.dig(:pending_persistence)
+            if persistence
+              persistence.concat(pending)
+              persistence << completion_thread if completion_thread
+            end
           else
             @pending_span_mutex.synchronize do
               @pending_span_threads[trace_id] << span_thread if span_thread && @pending_span_threads.key?(trace_id)
@@ -314,10 +331,14 @@ module Bitfab
         payload["testRunId"] = trace_state[:test_run_id]
       end
 
-      @http_client.send_external_trace(payload)
+      completion_thread = @http_client.send_external_trace(payload)
 
       # Clean up trace state
       TraceState.delete(trace_id)
+
+      # Returned so the replay path can join it — trace completions must be
+      # persisted before complete_replay builds the trace-ID mapping.
+      completion_thread
     end
 
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,

data/lib/bitfab/replay.rb

@@ -22,8 +22,12 @@ module Bitfab
 
     # Execute a block with replay context set on the current thread.
     # The context is automatically cleared when the block completes.
+    #
+    # pending_persistence, when given, collects the root span's persistence
+    # threads (span uploads + trace completion) so the replay runner can join
+    # them before complete_replay builds the trace-ID mapping.
     def with_context(test_run_id:, input_source_span_id: nil, input_source_trace_id: nil, trace_id: nil,
-      mock_tree: nil, mock_strategy: nil)
+      mock_tree: nil, mock_strategy: nil, pending_persistence: nil)
       previous = Thread.current[REPLAY_CONTEXT_KEY]
       ctx = {
         test_run_id:,
@@ -31,6 +35,7 @@ module Bitfab
         input_source_trace_id:,
         trace_id:
       }
+      ctx[:pending_persistence] = pending_persistence if pending_persistence
       if mock_tree
         ctx[:mock_tree] = mock_tree
         ctx[:mock_strategy] = mock_strategy || "none"
@@ -70,9 +75,16 @@ module Bitfab
     # @param mock [String] mock strategy for child spans: "none" (default),
     #   "all", or "marked". "all" mocks every child span; "marked" only mocks
     #   spans declared with mock_on_replay: true.
+    # @param adapt_inputs [#call, nil] optional hook to reshape recorded inputs
+    #   onto the method's current signature when its shape changed after the
+    #   traces were captured. Receives (args, kwargs, ctx) where ctx is
+    #   { trace_id:, source_span_id: }, and returns [new_args, new_kwargs]. Runs
+    #   per item inside the same rescue as the method, so a raising adapter sets
+    #   that item's :error rather than crashing 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, mock: "none")
+      code_change_description: nil, code_change_files: nil, experiment_group_id: nil, mock: "none",
+      adapt_inputs: nil)
       unless MOCK_STRATEGIES.include?(mock.to_s)
         raise ArgumentError, "Invalid mock strategy '#{mock}'. Must be one of: #{MOCK_STRATEGIES.join(", ")}"
       end
@@ -106,22 +118,69 @@ module Bitfab
       server_items = replay_data["items"] || []
 
       result_items = if server_items.any?
-        process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock.to_s)
+        process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock.to_s,
+          adapt_inputs)
       else
         []
       end
 
-      Bitfab.flush_traces
-
-      begin
-        complete_response = http_client.complete_replay(test_run_id)
-        trace_id_map = complete_response&.dig("traceIds") || {}
+      # Every item joined its own trace-persistence threads (span uploads +
+      # completion) in execute_item, so all replay traces are on the server
+      # by now — no flush needed, and complete_replay's trace-ID mapping is
+      # deterministic. complete_replay failures propagate: a missing mapping
+      # means verdicts can't be persisted, which callers must hear about
+      # loudly.
+      complete_response = http_client.complete_replay(test_run_id)
+      trace_id_map = complete_response&.dig("traceIds")
+
+      if trace_id_map.nil?
+        # Older servers don't return the mapping. Preserve the legacy
+        # nil-trace_id behavior but say why.
+        warn "Bitfab: server did not return replay trace IDs; item trace_id " \
+          "will be nil (server upgrade required for verdict persistence)"
+        result_items.each { |item| item[:trace_id] = nil }
+      else
+        # Map each item's locally-generated trace ID to the server's trace
+        # row ID. A completed item with no mapping means its trace was sent
+        # but the server has no record — a nil trace_id blocks verdict
+        # persistence and the Studio experiments view downstream, so this
+        # must never be silent.
+        #
+        # Severity splits on scope:
+        # - ALL completed items missing: systemic (the replayed method is
+        #   not traced, or uploads are wholesale broken). Raise; the run's
+        #   results are unusable for persistence.
+        # - SOME completed items missing: per-item upload failure (transient
+        #   network blip, one oversized payload). Nil those items and warn
+        #   loudly, but return the run so callers can persist verdicts for
+        #   the items that landed.
+        missing = []
+        completed_count = 0
         result_items.each do |item|
-          item[:trace_id] = trace_id_map[item[:trace_id]]
+          next unless item[:trace_id]
+
+          mapped = trace_id_map[item[:trace_id]]
+          if item[:error].nil?
+            completed_count += 1
+            missing << item[:trace_id] if mapped.nil?
+          end
+          item[:trace_id] = mapped
+        end
+        if missing.any?
+          trace_count = complete_response["traceCount"]
+          server_count = trace_count.nil? ? "" : " The server persisted #{trace_count} trace(s) for this run."
+          if missing.length == completed_count
+            raise "Replay completed but the server has no persisted trace for " \
+              "any of the #{completed_count} completed item(s) " \
+              "(test_run_id #{test_run_id}).#{server_count} Trace uploads were " \
+              "joined, so either the uploads failed or the replayed method is " \
+              "not traced (no root span was emitted)."
+          end
+          warn "Bitfab: server has no persisted trace for #{missing.length} of " \
+            "#{completed_count} completed replay item(s) " \
+            "(test_run_id #{test_run_id}).#{server_count} Their trace_id is nil " \
+            "and verdicts cannot be persisted for them. Missing: #{missing.join(", ")}"
         end
-      rescue => e
-        warn "Bitfab: Failed to complete replay: #{e.message}"
-        result_items.each { |item| item[:trace_id] = nil }
       end
 
       {
@@ -132,12 +191,13 @@ module Bitfab
     end
 
     # 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)
+    def process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock_strategy,
+      adapt_inputs = nil)
       concurrency = max_concurrency || server_items.length
 
       if concurrency <= 1
         server_items.map do |item|
-          process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy)
+          process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy, adapt_inputs)
         end
       else
         results_mutex = Mutex.new
@@ -151,7 +211,8 @@ module Bitfab
               item, idx = work_mutex.synchronize { work_queue.shift }
               break unless item
 
-              result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy)
+              result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
+                adapt_inputs)
               results_mutex.synchronize { results[idx] = result }
             end
           end
@@ -168,7 +229,8 @@ module Bitfab
     # deserializing inputs is captured on the returned item's :error rather
     # than propagated, so one bad trace never aborts the whole replay run
     # (mirrors the TypeScript and Python SDKs' per-item rescue).
-    def process_single_item(http_client, server_item, receiver, method_name, test_run_id, mock_strategy)
+    def process_single_item(http_client, server_item, receiver, method_name, test_run_id, mock_strategy,
+      adapt_inputs = nil)
       metrics = extract_server_item_metrics(server_item)
 
       span = http_client.get_external_span(server_item["externalSpanId"])
@@ -180,6 +242,8 @@ module Bitfab
         mock_tree = build_mock_tree(tree["root"] || {})
       end
 
+      adapt_ctx = {trace_id: server_item["traceId"], source_span_id: server_item["externalSpanId"]}
+
       execute_item(
         item_data,
         receiver,
@@ -189,7 +253,9 @@ module Bitfab
         metrics,
         input_source_trace_id: span["externalTraceId"],
         mock_strategy:,
-        mock_tree:
+        mock_tree:,
+        adapt_inputs:,
+        adapt_ctx:
       )
     rescue => e
       warn "Bitfab: replay item for span #{server_item["externalSpanId"]} failed before execution: #{e.message}"
@@ -280,12 +346,17 @@ module Bitfab
 
     # Execute a single replay item: deserialize inputs, call method with replay context.
     def execute_item(item, receiver, method_name, test_run_id, input_source_span_id = nil, metrics = {},
-      input_source_trace_id: nil, mock_strategy: "none", mock_tree: nil)
+      input_source_trace_id: nil, mock_strategy: "none", mock_tree: nil, adapt_inputs: nil, adapt_ctx: nil)
       args, kwargs = Serialize.deserialize_inputs(item)
 
       fn_result = nil
       fn_error = nil
       sdk_trace_id = SecureRandom.uuid
+      # Collects the root span's persistence threads (span uploads + trace
+      # completion). Joined below so this item's trace is on the server
+      # before run() calls complete_replay — otherwise the server's trace-ID
+      # mapping races the uploads and the item's trace_id comes back nil.
+      pending_persistence = []
 
       ReplayContext.with_context(
         test_run_id:,
@@ -293,8 +364,16 @@ module Bitfab
         input_source_trace_id:,
         trace_id: sdk_trace_id,
         mock_tree:,
-        mock_strategy:
+        mock_strategy:,
+        pending_persistence:
       ) do
+        # Reshape recorded inputs onto the current signature when an adapter is
+        # supplied. Inside the rescue so a raising adapter surfaces on this
+        # item's :error instead of crashing the run; args is reported on :input.
+        if adapt_inputs
+          ctx = adapt_ctx || {trace_id: nil, source_span_id: input_source_span_id}
+          args, kwargs = adapt_inputs.call(args, kwargs, ctx)
+        end
         fn_result = if kwargs.empty?
           receiver.send(method_name, *args)
         else
@@ -304,6 +383,12 @@ module Bitfab
         fn_error = e.message
       end
 
+      # Wait for this item's trace (spans + completion) to be fully persisted
+      # before the item resolves. Runs on the error path too — a raising
+      # method still emits a root span whose trace must land before
+      # complete_replay. Joins are bounded by the HTTP layer's own timeouts.
+      pending_persistence.each(&:join)
+
       {
         input: args,
         result: fn_result,

data/lib/bitfab/version.rb

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

metadata

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