bitfab 0.21.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 364e0ec3b3aa00cc47a398872911e18b1a3e5253f4448214da67f9c12af51814
-  data.tar.gz: 482340c71e8d2cb0f8ed92efa7a214278529a670e836e46b6209cc18126f230b
+  metadata.gz: d3286f80b5a55bff760f454480b1a3662fdf984174ee65d6f195dcbca5d456ed
+  data.tar.gz: d1d8bc8e244075f56cc6c06d42dae614da95b4531ea8bafc21de2b84b1d2526a
 SHA512:
-  metadata.gz: d9c10548592e02d52a74b96b268bea01d33200c3ff338b61758ec6d54dc2adcf07ca5c442212d464cb53cb86a1aeeccb7466c9ca71ba49810902ff6f5445b0b5
-  data.tar.gz: 3f12de6d0a9eeb5f7c8218d977c4d344a972f762f6c7380e5123d8976032c2215f63337698e4c7d6f18fd669786e4fded0084e0be2ef8fce1e7a696324c2f9b5
+  metadata.gz: 2ffbf4c36e417d4bf391eb9509a0136bc29dda1e54e191c84b51a59c400821fe7c21dbb796d272eaaca30f72502160d3aa8cb93efe1159304778422ac70ca9c1
+  data.tar.gz: 2dac975acb96571c6e7303ac7632cf3b099f3884ce3bf7f499dbfb35c71c357674868210906ebc6864dabb3a6645b7f82e41b4b8559553ab2a93304e2d106871

data/lib/bitfab/client.rb

@@ -425,9 +425,12 @@ module Bitfab
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
       span_name:, span_type:, function_name:, contexts:, prompt:, args:, kwargs:, result:, error:,
       started_at:, ended_at:, test_run_id: nil, input_source_span_id: nil)
-      # Human-readable JSON (input/output fields)
-      human_inputs = Serialize.serialize_inputs(args, kwargs)
-      human_output = Serialize.serialize_value(result)
+      # Human-readable JSON (input/output fields). The *_with_report variants
+      # also report what could not be faithfully captured so a lossy span is
+      # marked non-replayable below instead of shipping as if it round-trips.
+      human_inputs, input_dropped = Serialize.serialize_inputs_with_report(args, kwargs)
+      human_output, output_dropped = Serialize.serialize_value_with_report(result)
+      dropped = input_dropped + output_dropped
 
       # Marshal + Base64 for full Ruby-to-Ruby object reconstruction
       raw_input = (args.length == 1 && kwargs.empty?) ? args[0] : {args:, kwargs:}
@@ -469,6 +472,18 @@ module Bitfab
       }
       payload["testRunId"] = test_run_id if test_run_id
 
+      # A value that could only be captured as a placeholder makes the span
+      # non-replayable; record it on the payload's errors (matching the Python
+      # and TypeScript SDKs) instead of shipping the lossy capture silently.
+      unless dropped.empty?
+        names = dropped.uniq.sort.join(", ")
+        payload["errors"] = [{
+          "source" => "sdk",
+          "step" => "serialization_degraded",
+          "error" => "non-replayable: could not faithfully capture #{names}"
+        }]
+      end
+
       @http_client.send_external_span(payload) # Returns the background thread
     end
 

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/replay.rb

@@ -102,8 +102,12 @@ 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",
@@ -254,14 +258,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 +285,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 +303,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/serialize.rb

@@ -29,28 +29,44 @@ module Bitfab
     #   Without this the wire-side JSON.dump in the http client can produce a
     #   request that times out or gets rejected, leaving a trace with zero spans.
     def serialize_value(value)
-      result = serialize_value_inner(value, 0)
-      return result unless oversized?(result)
+      serialize_value_with_report(value).first
+    end
 
-      unserializable_stub(value, "too_large")
+    # Like serialize_value, but also reports what could not be faithfully
+    # captured. Returns [result, dropped] where dropped lists the class name (or
+    # "max_depth"/"too_large") behind every placeholder the walk had to emit. A
+    # non-empty dropped means the capture is lossy, so the send boundary marks
+    # the span serialization_degraded (non-replayable) instead of shipping it as
+    # if it round-trips. Mirrors the Python/TS SDKs' report serializers.
+    def serialize_value_with_report(value)
+      dropped = []
+      result = serialize_value_inner(value, 0, dropped)
+      if oversized?(result)
+        dropped << "too_large"
+        return [unserializable_stub(value, "too_large"), dropped]
+      end
+      [result, dropped]
     rescue StandardError, SystemStackError
-      unserializable_stub(value, "unexpected_error")
+      [unserializable_stub(value, "unexpected_error"), [class_name(value)]]
     end
 
-    def serialize_value_inner(value, depth)
-      return "<unserializable: max_depth>" if depth > MAX_SERIALIZE_DEPTH
+    def serialize_value_inner(value, depth, dropped = [])
+      if depth > MAX_SERIALIZE_DEPTH
+        dropped << "max_depth"
+        return "<unserializable: max_depth>"
+      end
 
       case value
       when nil, true, false, Integer, Float, String
         value
       when Hash
         value.each_with_object({}) do |(k, v), acc|
-          acc[safe_to_s(k)] = serialize_value_inner(v, depth + 1)
+          acc[safe_to_s(k)] = serialize_value_inner(v, depth + 1, dropped)
         end
       when Array
-        value.map { |v| serialize_value_inner(v, depth + 1) }
+        value.map { |v| serialize_value_inner(v, depth + 1, dropped) }
       when Set
-        value.map { |v| serialize_value_inner(v, depth + 1) }
+        value.map { |v| serialize_value_inner(v, depth + 1, dropped) }
       when Time, DateTime
         safely_call(value, "iso8601", 3) { safe_to_s(value) }
       when Date
@@ -59,16 +75,26 @@ module Bitfab
         value.to_s
       else
         if value.respond_to?(:to_h)
-          h = safely_call(value, "to_h") { return unserializable_stub(value, "to_h_raised") }
-          serialize_value_inner(h, depth + 1)
+          h = safely_call(value, "to_h") do
+            dropped << class_name(value)
+            return unserializable_stub(value, "to_h_raised")
+          end
+          serialize_value_inner(h, depth + 1, dropped)
         elsif value.respond_to?(:to_a)
-          a = safely_call(value, "to_a") { return unserializable_stub(value, "to_a_raised") }
-          serialize_value_inner(a, depth + 1)
+          a = safely_call(value, "to_a") do
+            dropped << class_name(value)
+            return unserializable_stub(value, "to_a_raised")
+          end
+          serialize_value_inner(a, depth + 1, dropped)
         else
+          # An arbitrary object with no structured conversion: stringifying it is
+          # a lossy capture (a repr, not its data), so report it as dropped.
+          dropped << class_name(value)
           safe_to_s(value)
         end
       end
     rescue StandardError, SystemStackError
+      dropped << class_name(value)
       unserializable_stub(value, "inner_error")
     end
 
@@ -108,14 +134,27 @@ module Bitfab
 
     # Serialize function inputs (args + kwargs) for span data (human-readable).
     def serialize_inputs(args, kwargs = {})
-      serialized = args.map { |arg| serialize_value(arg) }
+      serialize_inputs_with_report(args, kwargs).first
+    end
+
+    # Like serialize_inputs, but also returns the accumulated dropped list so the
+    # send boundary can mark a lossy capture non-replayable.
+    def serialize_inputs_with_report(args, kwargs = {})
+      dropped = []
+      serialized = args.map do |arg|
+        result, arg_dropped = serialize_value_with_report(arg)
+        dropped.concat(arg_dropped)
+        result
+      end
       unless kwargs.empty?
         kw = kwargs.each_with_object({}) do |(k, v), acc|
-          acc[safe_to_s(k)] = serialize_value(v)
+          result, v_dropped = serialize_value_with_report(v)
+          dropped.concat(v_dropped)
+          acc[safe_to_s(k)] = result
         end
         serialized << kw
       end
-      serialized
+      [serialized, dropped]
     end
 
     # Marshal a value to a Base64-encoded string for Ruby-to-Ruby reconstruction.

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.21.1"
+  VERSION = "0.22.0"
 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.1
+  version: 0.22.0
 platform: ruby
 authors:
 - Harvest Team