bitfab 0.21.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7536f774b491c131b04a135a41c5f753c7c507615e54aa675c314cff785b08df
-  data.tar.gz: 47e7804161bc40563f5aca99147ef43d2af1af6d73d22f6ad3ae3402ea4b51f4
+  metadata.gz: 364e0ec3b3aa00cc47a398872911e18b1a3e5253f4448214da67f9c12af51814
+  data.tar.gz: 482340c71e8d2cb0f8ed92efa7a214278529a670e836e46b6209cc18126f230b
 SHA512:
-  metadata.gz: 4aed7d077e6aa0ca89e8130b526578276591e60b41ae10670dc14db4eaca6221c30481dcad84acb8d7dfd7e549b2b92aa2c5a750efa36c4df85224b01360fe19
-  data.tar.gz: d73a3933eceba9c705fdab9f8b38f9f46766e026e59cdf61ee0ca2ea49a01ec4e5029fcbc87161a0a16602a2365ef3eeddba1acff27e659bf8fcf69b08d85138
+  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
@@ -101,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/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.21.0"
+  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.21.0
+  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