bitfab 0.36.1 → 0.36.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0b827ad6e9bca08b3025f9c2419290910999a5985705369e6375aee8091232c
-  data.tar.gz: e6e0a414013d3bee0efda22415430d9690fe537973a36e5f3dda540fcda3d5e4
+  metadata.gz: deea3052760a7b677216225f0cd030f4931995b1d10e6b7396c97a57a27ab9c1
+  data.tar.gz: 5f64a512db5c8c79f092e5bbf92e16adfc2e20a4a07c869eafab48fb42db5665
 SHA512:
-  metadata.gz: ee72cf5ed5c81ad34dbd4d980091523c90c7cb1d11fc716499ab5f604f1829f5653851350942b2cea6660e20e67c065ae8807e0778153a0ccf08a1397cc08491
-  data.tar.gz: 297efa6c3e5d9b1086536dd5e560168e9f9d4c638638b562a67d69ccb1c37253534da6447778032f93e186532f0a563eb7b7f41148eb6b9e0e2ac91c4ed2196e
+  metadata.gz: f9024ab4975b3963e4d2c91aa903b3e4bc7880791aa1f0a4132a9ee847e54e2132339246cbc1067beba8a2130e813738474fcc40a38a1d3b9a0e19ba92633834
+  data.tar.gz: b3c4b7c252a566192362e6d1a3e4d31bcad55f752a70527fce5de87ebc9ab75c4839a02fd5d67589823ee36003f3fcb49d5bdade0a315dc8a22971b9769ea9c3

data/lib/bitfab/http_client.rb

@@ -181,9 +181,11 @@ module Bitfab
       request("/api/sdk/replay/start", payload, timeout:)
     end
 
-    # Fetch an external span by ID. Blocking GET request.
-    def get_external_span(span_id)
-      get("/api/sdk/externalSpans/#{span_id}", timeout: 30)
+    # Fetch an external span by ID. Blocking GET request. The replay view keeps
+    # only the input/output serialization fields used by replay.
+    def get_external_span(span_id, replay_view: false)
+      query = replay_view ? "?view=replay" : ""
+      get("/api/sdk/externalSpans/#{span_id}#{query}", timeout: 30)
     end
 
     def get_trace_span(trace_id, id: nil, name: nil, occurrence: "last")
@@ -210,9 +212,12 @@ module Bitfab
     # payloads so only the spans actually mocked are fetched later (by
     # externalSpanId), avoiding dragging down every span's output when only a
     # few are mocked.
-    def get_span_tree(external_span_id, include_outputs: true)
+    def get_span_tree(external_span_id, include_outputs: true, include_root_output: true)
       endpoint = "/api/sdk/replay/spanTree/#{external_span_id}"
-      endpoint += "?includeOutputs=false" unless include_outputs
+      query = []
+      query << "includeOutputs=false" unless include_outputs
+      query << "includeRootOutput=false" unless include_root_output
+      endpoint += "?#{query.join("&")}" unless query.empty?
       get(endpoint, timeout: 30)
     end
 

data/lib/bitfab/replay.rb

@@ -12,6 +12,30 @@ require_relative "traceable"
 require_relative "transport"
 
 module Bitfab
+  # A requested replay database branch could not be resolved. The resolver code
+  # and original message remain structured for callers to inspect.
+  class DbBranchReplayError < StandardError
+    attr_reader :code, :original_trace_id
+
+    def initialize(code, message, original_trace_id)
+      super(message)
+      @code = code
+      @original_trace_id = original_trace_id
+    end
+  end
+
+  # Whole-run replay failure with every item collected before the run failed.
+  class ReplayError < StandardError
+    attr_reader :items, :test_run_id, :test_run_url
+
+    def initialize(message, items:, test_run_id:, test_run_url:)
+      super(message)
+      @items = items
+      @test_run_id = test_run_id
+      @test_run_url = test_run_url
+    end
+  end
+
   # Replay mock strategies. Mirrors the Python and TypeScript SDKs.
   #
   # - "marked" : only spans declared with mock_on_replay: true return historical
@@ -85,6 +109,50 @@ module Bitfab
 
     module_function
 
+    def json_safe(value)
+      case value
+      when Exception
+        serialized = {type: value.class.name, message: value.message, backtrace: value.backtrace}
+        if value.is_a?(DbBranchReplayError)
+          serialized[:code] = value.code
+          serialized[:original_trace_id] = value.original_trace_id
+          serialized[:cause] = json_safe(value.cause) if value.cause
+        end
+        serialized
+      when Hash
+        value.to_h { |key, child| [key, json_safe(child)] }
+      when Array
+        value.map { |child| json_safe(child) }
+      else
+        value
+      end
+    end
+
+    def replay_item_error_message(error)
+      return error.message unless error.is_a?(DbBranchReplayError)
+
+      "Replay requested a database branch for trace #{error.original_trace_id} but it " \
+        "could not be resolved (#{error.code}): #{error.message}. The method was not run, " \
+        "because replaying it against the live database would produce a result that looks " \
+        "valid but did not use the historical data you asked for."
+    end
+
+    def public_replay_items(items)
+      items.map { |item| item.except(:_sdk_trace_id) }
+    end
+
+    def preserve_replay_failure(items, test_run_id, test_run_url)
+      yield
+    rescue => cause
+      error = ReplayError.new(
+        cause.message,
+        items: public_replay_items(items),
+        test_run_id:,
+        test_run_url:
+      )
+      raise error, cause:
+    end
+
     # Replay historical traces through a method and create a test run.
     #
     # Fetches the last N traces for the given trace function key, re-runs each
@@ -223,6 +291,7 @@ module Bitfab
       )
       test_run_id = replay_data["testRunId"]
       test_run_url = replay_data["testRunUrl"]
+      full_test_run_url = "#{client.service_url}#{test_run_url}"
       server_items = replay_data["items"] || []
 
       result_items = if server_items.any?
@@ -237,12 +306,16 @@ module Bitfab
       # to finalize once the server confirms every replay trace it queued: the
       # trace-ID mapping complete_replay builds would otherwise race the
       # in-flight batches and hand back nil for every item.
-      wait_for_replay_persistence(http_client, test_run_id, result_items.map { |item| item[:_sdk_trace_id] })
+      preserve_replay_failure(result_items, test_run_id, full_test_run_url) do
+        wait_for_replay_persistence(http_client, test_run_id, result_items.map { |item| item[:_sdk_trace_id] })
+      end
 
       # complete_replay finalizes the run and returns the token/diagnostic
       # mapping; its failures propagate loudly because a run that never
       # completed can't be finalized.
-      complete_response = http_client.complete_replay(test_run_id)
+      complete_response = preserve_replay_failure(result_items, test_run_id, full_test_run_url) do
+        http_client.complete_replay(test_run_id)
+      end
       trace_id_map = complete_response&.dig("traceIds")
       # Per-replay-trace token usage keyed by server trace id: the REPLAYED
       # run's tokens (span-aggregated server-side), used below to fill each
@@ -278,11 +351,18 @@ module Bitfab
         if completed_count.positive? && missing.length == completed_count
           trace_count = complete_response["traceCount"]
           server_count = trace_count.nil? ? "" : " The server persisted #{trace_count} trace(s) for this run."
-          raise "Replay completed but the server has no persisted trace for " \
+          cause = RuntimeError.new("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 " \
             "flushed, so either the uploads failed or the replayed method is " \
-            "not traced (no root span was emitted)."
+            "not traced (no root span was emitted).")
+          error = ReplayError.new(
+            cause.message,
+            items: public_replay_items(result_items),
+            test_run_id:,
+            test_run_url: full_test_run_url
+          )
+          raise error, cause:
         end
         # SOME completed items missing: per-item upload failure. Warn, but
         # return the run; the items that landed can still be labeled.
@@ -301,7 +381,7 @@ module Bitfab
       result = {
         items: result_items,
         test_run_id:,
-        test_run_url: "#{client.service_url}#{test_run_url}"
+        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):
@@ -543,7 +623,7 @@ module Bitfab
       begin
         dir = File.dirname(result_path)
         FileUtils.mkdir_p(dir) unless dir.nil? || dir.empty? || dir == "."
-        File.write(result_path, "#{JSON.pretty_generate(result)}\n")
+        File.write(result_path, "#{Bitfab.serialize_replay_result(result)}\n")
       rescue => e
         warn "Bitfab: failed to write replay result to BITFAB_REPLAY_RESULT_PATH (#{result_path}): #{e.message}"
       end
@@ -593,6 +673,8 @@ module Bitfab
                 result: result[:result],
                 original_output: result[:original_output],
                 error:,
+                trace_error: result[:trace_error],
+                replay_error: result[:replay_error],
                 duration_ms: result[:duration_ms],
                 tokens: result[:tokens],
                 model: result[:model],
@@ -664,19 +746,29 @@ module Bitfab
       lease_error = include_db_branch_lease ? server_item["dbBranchLeaseError"] : nil
       db_snapshot_ref = server_item["dbSnapshotRef"]
       if include_db_branch_lease && lease.nil? && lease_error.nil?
-        resolved = http_client.resolve_db_branch_lease(test_run_id, original_trace_id, db_branch_settings)
+        begin
+          resolved = http_client.resolve_db_branch_lease(test_run_id, original_trace_id, db_branch_settings)
+        rescue => cause
+          error = DbBranchReplayError.new(
+            "lease_request_failed",
+            "Bitfab could not request the database branch: #{cause.message}",
+            original_trace_id
+          )
+          raise error, cause:
+        end
         lease = resolved["lease"]
         lease_error = resolved["leaseError"]
         db_snapshot_ref = resolved["dbSnapshotRef"] || db_snapshot_ref
       end
       if lease_error
-        raise "Replay requested a database branch for trace #{original_trace_id} but it " \
-          "could not be resolved (#{lease_error["code"]}): #{lease_error["message"]}. " \
-          "The method was not run, because replaying it against the live database would " \
-          "produce a result that looks valid but did not use the historical data you asked for."
+        raise DbBranchReplayError.new(
+          lease_error["code"].to_s,
+          lease_error["message"].to_s,
+          original_trace_id
+        )
       end
 
-      span = http_client.get_external_span(original_span_id)
+      span = http_client.get_external_span(original_span_id, replay_view: true)
       item_data = extract_span_data(span)
 
       # Fetch the span tree when the base strategy needs recorded outputs
@@ -694,7 +786,11 @@ module Bitfab
       mock_tree = nil
       if mock_strategy == "all" || mock_strategy == "marked" || overrides_present
         begin
-          tree = http_client.get_span_tree(original_span_id, include_outputs:)
+          tree = http_client.get_span_tree(
+            original_span_id,
+            include_outputs:,
+            include_root_output: false
+          )
           mock_tree = build_mock_tree(tree["root"] || {})
         rescue Exception => e # rubocop:disable Lint/RescueException
           raise if e.is_a?(SystemExit) || e.is_a?(SignalException)
@@ -748,7 +844,9 @@ module Bitfab
         input: [],
         result: nil,
         original_output: nil,
-        error: e.message,
+        error: replay_item_error_message(e),
+        trace_error: nil,
+        replay_error: e,
         duration_ms: metrics&.dig(:duration_ms),
         tokens: metrics&.dig(:tokens),
         model: metrics&.dig(:model),
@@ -843,7 +941,7 @@ module Bitfab
       lambda do |external_span_id|
         return cache[external_span_id] if cache.key?(external_span_id)
 
-        span = http_client.get_external_span(external_span_id)
+        span = http_client.get_external_span(external_span_id, replay_view: true)
         span_data = (span["rawData"] || {})["span_data"] || {}
         # Prefer the Ruby Marshal payload (output_serialized) written by this
         # SDK; fall back to another SDK's output_meta, then the raw JSON output.
@@ -937,51 +1035,64 @@ module Bitfab
 
       fn_result = nil
       fn_error = nil
+      replay_error = nil
       # Client-side correlation id that tags this item's replay spans so the
       # server can echo back the row id it minted (resolved in run()'s
       # complete-replay loop). Carried on the item under :_sdk_trace_id, never
       # surfaced as the public :trace_id.
       sdk_trace_id = SecureRandom.uuid
 
-      ReplayContext.with_context(
-        test_run_id:,
-        input_source_span_id:,
-        input_source_trace_id:,
-        trace_id: sdk_trace_id,
-        mock_tree:,
-        mock_strategy:,
-        mock_overrides:,
-        fetch_span_output:,
-        db_branch_lease:,
-        source_bitfab_trace_id:
-      ) 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 || {
-            original_trace_id: nil,
-            original_span_id: input_source_span_id,
-            # Deprecated aliases for original_trace_id/original_span_id.
-            source_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
-          receiver.send(method_name, *args, **kwargs)
+      begin
+        ReplayContext.with_context(
+          test_run_id:,
+          input_source_span_id:,
+          input_source_trace_id:,
+          trace_id: sdk_trace_id,
+          mock_tree:,
+          mock_strategy:,
+          mock_overrides:,
+          fetch_span_output:,
+          db_branch_lease:,
+          source_bitfab_trace_id:
+        ) do
+          begin
+            if adapt_inputs
+              ctx = adapt_ctx || {
+                original_trace_id: nil,
+                original_span_id: input_source_span_id,
+                # Deprecated aliases for original_trace_id/original_span_id.
+                source_trace_id: nil,
+                source_span_id: input_source_span_id
+              }
+              args, kwargs = adapt_inputs.call(args, kwargs, ctx)
+            end
+          rescue => e
+            replay_error = e
+          end
+          if replay_error.nil?
+            begin
+              fn_result = if kwargs.empty?
+                receiver.send(method_name, *args)
+              else
+                receiver.send(method_name, *args, **kwargs)
+              end
+            rescue => e
+              fn_error = e
+            end
+          end
         end
       rescue => e
-        fn_error = e.message
+        replay_error = e
       end
 
+      item_error = fn_error || replay_error
       {
         input: args,
         result: fn_result,
         original_output: item["output"],
-        error: fn_error,
+        error: item_error&.message,
+        trace_error: fn_error,
+        replay_error:,
         duration_ms: metrics[:duration_ms],
         tokens: metrics[:tokens],
         model: metrics[:model],

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -159,9 +159,14 @@ module Bitfab
     #   succeeded, errored, and item (the object replay already passes to
     #   on_progress)
     def report_replay_progress(progress)
-      warn "#{BITFAB_PROGRESS_PREFIX}#{progress.to_json}"
+      warn "#{BITFAB_PROGRESS_PREFIX}#{Replay.json_safe(progress).to_json}"
     rescue
       nil
     end
+
+    # Serialize a replay result while retaining structured exception fields.
+    def serialize_replay_result(result)
+      JSON.pretty_generate(Replay.json_safe(result))
+    end
   end
 end

metadata

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