bitfab 0.20.2 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2428cc39dcd97d154e36ba9792628478e86a4b4dde5101c79d37ebb1635378f
-  data.tar.gz: effa0dba40674696ad3d9155615d9d9e2e40a3fe7f9aed9c8ee97516985e13c6
+  metadata.gz: 364e0ec3b3aa00cc47a398872911e18b1a3e5253f4448214da67f9c12af51814
+  data.tar.gz: 482340c71e8d2cb0f8ed92efa7a214278529a670e836e46b6209cc18126f230b
 SHA512:
-  metadata.gz: 5f172f0178829a08315ae1caf3de6ff4a22389b2f83dbf449721ca53ca3a466580af00c15bd5279dffc2c9d074aee2afd0e157733f9257987460ef8d101350c9
-  data.tar.gz: 9c6af19d4ebac35d13280aeaa89ac6104cbff3020e24813e292e4170c6524016a0df943025f3ced5510345c863e4b86f9f027fe281912e99a6438f863dde9d28
+  metadata.gz: d9c10548592e02d52a74b96b268bea01d33200c3ff338b61758ec6d54dc2adcf07ca5c442212d464cb53cb86a1aeeccb7466c9ca71ba49810902ff6f5445b0b5
+  data.tar.gz: 3f12de6d0a9eeb5f7c8218d977c4d344a972f762f6c7380e5123d8976032c2215f63337698e4c7d6f18fd669786e4fded0084e0be2ef8fce1e7a696324c2f9b5

data/lib/bitfab/client.rb

@@ -8,6 +8,7 @@ require_relative "http_client"
 require_relative "replay"
 require_relative "span_context"
 require_relative "serialize"
+require_relative "warn_once"
 
 module Bitfab
   class Client
@@ -59,14 +60,21 @@ module Bitfab
     #   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].
+    # @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.
     # @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",
-      adapt_inputs: nil, environment: nil)
+      adapt_inputs: nil, environment: nil, on_progress: nil)
       Replay.run(
         self, receiver, method_name,
         trace_function_key:, limit:, trace_ids:, max_concurrency:,
-        code_change_description:, code_change_files:, experiment_group_id:, dataset_id:, mock:, adapt_inputs:, environment:
+        code_change_description:, code_change_files:, experiment_group_id:, dataset_id:, mock:, adapt_inputs:, environment:,
+        on_progress:
       )
     end
 
@@ -94,59 +102,93 @@ module Bitfab
       mock_on_replay: false)
       return yield unless @enabled
 
-      parent = SpanContext.current
-      replay_ctx = ReplayContext.current
-      trace_id = parent ? parent[:trace_id] : (replay_ctx&.dig(:trace_id) || SecureRandom.uuid)
-      span_id = SecureRandom.uuid
-      parent_span_id = parent&.dig(:span_id)
-      is_root_span = parent_span_id.nil?
-      started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
-      resolved_test_run_id = replay_ctx&.dig(:test_run_id)
-      resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
-      resolved_input_source_trace_id = replay_ctx&.dig(:input_source_trace_id)
-
-      # Register trace state for root spans
-      if is_root_span && !TraceState.get(trace_id)
-        TraceState.create(
-          trace_id,
-          test_run_id: resolved_test_run_id,
-          input_source_trace_id: resolved_input_source_trace_id
-        )
-      end
+      # Span setup runs before the user's block. Tracing is a side-channel, so
+      # if anything here raises (id generation, trace-state bookkeeping, a
+      # malformed replay mock tree) the user's method must still run. On failure
+      # we clean up any partially registered trace state, warn once, and run the
+      # block untraced. `trace_id` is declared out here so the rescue can clean
+      # it up; the other locals stay visible to the real path below.
+      trace_id = nil
+      span_id = nil
+      parent_span_id = nil
+      is_root_span = nil
+      started_at = nil
+      resolved_test_run_id = nil
+      resolved_input_source_span_id = nil
+      begin
+        parent = SpanContext.current
+        replay_ctx = ReplayContext.current
+        trace_id = parent ? parent[:trace_id] : (replay_ctx&.dig(:trace_id) || SecureRandom.uuid)
+        span_id = SecureRandom.uuid
+        parent_span_id = parent&.dig(:span_id)
+        is_root_span = parent_span_id.nil?
+        started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+        resolved_test_run_id = replay_ctx&.dig(:test_run_id)
+        resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
+        resolved_input_source_trace_id = replay_ctx&.dig(:input_source_trace_id)
+
+        # Register trace state for root spans
+        if is_root_span && !TraceState.get(trace_id)
+          TraceState.create(
+            trace_id,
+            test_run_id: resolved_test_run_id,
+            input_source_trace_id: resolved_input_source_trace_id
+          )
+        end
 
-      if is_root_span
-        @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
-      end
+        if is_root_span
+          @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
+        end
 
-      # Advance the per-(key, name) call counter for any non-root span under
-      # an active mock tree, even when this span won't itself be mocked.
-      # Unmarked spans must consume an index so subsequent marked siblings
-      # line up with `build_mock_tree`'s sequential numbering for the same
-      # (key, name) pair. Different (key, name) pairs have independent
-      # counters: they cannot shift each other.
-      call_index = advance_mock_counter(replay_ctx, trace_function_key, span_name, is_root_span:)
-      if call_index
-        mocked_output = check_mock_replay(
-          replay_ctx, trace_function_key, span_name, call_index, mock_on_replay:
-        )
-        if mocked_output != MOCK_REPLAY_MISS
-          send_mocked_span(
-            trace_function_key:,
-            trace_id:,
-            span_id:,
-            parent_span_id:,
-            span_name:,
-            span_type:,
-            function_name:,
-            args:,
-            kwargs:,
-            mocked_output:,
-            started_at:,
-            test_run_id: resolved_test_run_id,
-            input_source_span_id: resolved_input_source_span_id
+        # Advance the per-(key, name) call counter for any non-root span under
+        # an active mock tree, even when this span won't itself be mocked.
+        # Unmarked spans must consume an index so subsequent marked siblings
+        # line up with `build_mock_tree`'s sequential numbering for the same
+        # (key, name) pair. Different (key, name) pairs have independent
+        # counters: they cannot shift each other.
+        call_index = advance_mock_counter(replay_ctx, trace_function_key, span_name, is_root_span:)
+        if call_index
+          mocked_output = check_mock_replay(
+            replay_ctx, trace_function_key, span_name, call_index, mock_on_replay:
           )
-          return mocked_output
+          if mocked_output != MOCK_REPLAY_MISS
+            send_mocked_span(
+              trace_function_key:,
+              trace_id:,
+              span_id:,
+              parent_span_id:,
+              span_name:,
+              span_type:,
+              function_name:,
+              args:,
+              kwargs:,
+              mocked_output:,
+              started_at:,
+              test_run_id: resolved_test_run_id,
+              input_source_span_id: resolved_input_source_span_id
+            )
+            return mocked_output
+          end
+        end
+      rescue
+        # Clean up any trace state this partial setup registered so it does not
+        # leak.
+        if trace_id
+          TraceState.delete(trace_id)
+          @pending_span_mutex.synchronize { @pending_span_threads.delete(trace_id) }
         end
+        # During replay (a controlled eval) a setup failure must surface, not
+        # silently run the block untraced: swallowing it would execute real code
+        # with real side effects and skew the mock call counter, defeating the
+        # replay. The never-crash fallback is for production hosts only.
+        raise if ReplayContext.current
+
+        Bitfab.warn_once(
+          "span-setup:#{trace_function_key}",
+          "span setup failed for '#{trace_function_key}'; this call runs untraced. " \
+          "Your method still executes and returns normally."
+        )
+        return yield
       end
 
       result = nil

data/lib/bitfab/http_client.rb

@@ -7,6 +7,7 @@ require "uri"
 require_relative "constants"
 require_relative "serialize"
 require_relative "version"
+require_relative "warn_once"
 
 module Bitfab
   class HttpClient
@@ -181,14 +182,13 @@ module Bitfab
     def safe_generate(payload, endpoint)
       JSON.generate(payload)
     rescue => e
-      begin
-        warn "Bitfab: request body to #{endpoint} held a non-serializable " \
-             "value (#{e.message}); it was stubbed so the span still sends, " \
-             "but the trace may be incomplete or not replayable. Capture a " \
-             "JSON-safe projection of this input to make it replayable."
-      rescue
-        # Never crash the host app over a log line.
-      end
+      Bitfab.warn_once(
+        "request-body-stubbed",
+        "a request body held a non-serializable value (#{e.message}); it was " \
+        "stubbed so the span still sends, but the trace may be incomplete or " \
+        "not replayable. Capture a JSON-safe projection of this input to make " \
+        "it replayable."
+      )
 
       begin
         JSON.generate(sanitize_payload(payload))
@@ -242,11 +242,11 @@ module Bitfab
       thread = Thread.new do
         block.call
       rescue => e
-        begin
-          warn "Bitfab: Failed to send request: #{e.message}"
-        rescue
-          # Never crash the host app
-        end
+        Bitfab.warn_once(
+          "send-request-failed",
+          "failed to send a request to the backend (further occurrences " \
+          "suppressed): #{e.message}"
+        )
       ensure
         @pending_threads_mutex.synchronize { @pending_threads.delete(Thread.current) }
       end

data/lib/bitfab/replay.rb

@@ -100,10 +100,14 @@ module Bitfab
     #   { 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.
+    # @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.
     # @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",
-      adapt_inputs: nil, environment: nil)
+      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(", ")}"
       end
@@ -157,7 +161,7 @@ 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)
+          adapt_inputs, include_db_branch_lease, on_progress:)
       else
         []
       end
@@ -237,13 +241,39 @@ 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)
+      adapt_inputs = nil, include_db_branch_lease = false, on_progress: nil)
       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.
+      total = server_items.length
+      progress_mutex = Mutex.new
+      completed = 0
+      succeeded = 0
+      errored = 0
+      report = lambda do |result|
+        return unless on_progress
+
+        progress_mutex.synchronize do
+          completed += 1
+          result[:error].nil? ? (succeeded += 1) : (errored += 1)
+          begin
+            on_progress.call({completed:, total:, succeeded:, errored:})
+          rescue => e
+            warn "Bitfab: replay on_progress callback raised: #{e.message}"
+          end
+        end
+      end
+
       if concurrency <= 1
         server_items.map do |item|
-          process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy, adapt_inputs,
-            include_db_branch_lease)
+          result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
+            adapt_inputs, include_db_branch_lease)
+          report.call(result)
+          result
         end
       else
         results_mutex = Mutex.new
@@ -260,6 +290,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)
             end
           end
         end

data/lib/bitfab/traceable.rb

@@ -173,7 +173,12 @@ module Bitfab
 
         wrapper = Module.new do
           define_method(method_name) do |*args, **kwargs, &block|
-            Bitfab.client.send(:execute_span,
+            # If Bitfab was never configured, run the real method untraced
+            # rather than raising a "not configured" error into the host app.
+            client = Bitfab.client_or_nil
+            return super(*args, **kwargs, &block) unless client
+
+            client.send(:execute_span,
               trace_function_key:,
               span_name:,
               span_type: type,

data/lib/bitfab/version.rb

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

data/lib/bitfab/warn_once.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bitfab
+  # Emit a warning at most once per distinct key for the life of the process.
+  #
+  # The SDK must never crash or spam the host app, so every failure on the
+  # user's path degrades quietly: a span is dropped, a call runs untraced, a
+  # payload is stubbed. Silent is safe but undebuggable; warning on every call
+  # from a hot path is its own problem. A one-time warning per distinct issue
+  # restores the signal without the flood. Keys should identify the specific
+  # degradation (e.g. include the trace_function_key) so each distinct issue
+  # warns once, not just the first one seen.
+  @warn_once_seen = Set.new
+  @warn_once_mutex = Mutex.new
+
+  class << self
+    def warn_once(key, message)
+      @warn_once_mutex.synchronize do
+        return if @warn_once_seen.include?(key)
+
+        @warn_once_seen.add(key)
+      end
+      begin
+        warn "Bitfab: #{message}"
+      rescue Exception # rubocop:disable Lint/RescueException
+        # Logging must never crash the host app (e.g. a closed $stderr).
+      end
+    end
+
+    # Test-only: clear the dedup set so a warning can fire again.
+    def _reset_warn_once
+      @warn_once_mutex.synchronize { @warn_once_seen.clear }
+    end
+  end
+end

data/lib/bitfab.rb

@@ -2,6 +2,7 @@
 
 require_relative "bitfab/version"
 require_relative "bitfab/constants"
+require_relative "bitfab/warn_once"
 require_relative "bitfab/serialize"
 require_relative "bitfab/db_snapshot"
 require_relative "bitfab/span_context"
@@ -65,6 +66,13 @@ module Bitfab
       @client or raise "Bitfab not configured. Call Bitfab.configure(api_key: '...') first."
     end
 
+    # Returns the global client, or nil if not configured. Used on the traced
+    # call path so a method invoked before Bitfab.configure runs untraced
+    # rather than crashing the host app with a "not configured" error.
+    def client_or_nil
+      @client
+    end
+
     # Reset the global client (primarily for testing).
     def reset!
       @client = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.20.2
+  version: 0.21.1
 platform: ruby
 authors:
 - Harvest Team
@@ -127,6 +127,7 @@ files:
 - lib/bitfab/span_context.rb
 - lib/bitfab/traceable.rb
 - lib/bitfab/version.rb
+- lib/bitfab/warn_once.rb
 homepage: https://bitfab.ai
 licenses:
 - MIT