bitfab 0.22.1 → 0.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb8d7ab7e95fed00c067b1653c4d8271c1814b6a9d42bc8ffbb320596ac2190e
-  data.tar.gz: 6050620ec20d4172045e7a7c29930349e488cd886132cb54758ca98d789be34f
+  metadata.gz: 3827f24f9f67b8264b588233b5e1eb3ffe6581dca039951a391253a87cf7c10b
+  data.tar.gz: 744d87d7188cb454c03242b95ff0ba7e1a0c0d53f131df9aff7449920ec69414
 SHA512:
-  metadata.gz: c94a534717dfbf682ca6d4f1fb6e9501fba8df1057bd6390457c4f561616a23bf53092bfc4bc8cc966f67037d1a7a9b8f2eadc4edff92645a99e2b0a9ffcf33b
-  data.tar.gz: 7e416c3b5af6248ada3bda42d56d2853d68792e7adcf3bb4a1e1af98b5b4740ee92cd7e25ba8c86fee0bc0b0acaa5acd102bb1d8e561d03d0e669d24de877048
+  metadata.gz: 4a376efa4cba26a1aff6728acea5deded7982f12fcc60fe586dbc84850653a2649565bdf88d3ac49eb2ddaac78c4e257533a22aebf5fbe8b559f4dd0699e572f
+  data.tar.gz: 726b98d0e1516d621bed5bda08b26fc62a47fbdcc3b3bfd17777208513b3c5979213761aa1175cb7ec18d4351fe729f49562fcbea3ddf73d5d1744f25f308c25

data/lib/bitfab/client.rb

@@ -20,21 +20,40 @@ module Bitfab
     # outputs (which may themselves be nil or false).
     MOCK_REPLAY_MISS = Object.new.freeze
 
-    attr_reader :api_key, :service_url, :enabled
+    attr_reader :service_url
 
-    def initialize(api_key:, service_url: nil, enabled: true)
-      @api_key = api_key
+    def initialize(api_key: nil, service_url: nil, enabled: true, strict: false)
+      @api_key_config = api_key
       @service_url = service_url || DEFAULT_SERVICE_URL
-      @enabled = enabled
-      if @enabled && (@api_key.nil? || @api_key.to_s.strip.empty?)
-        warn "Bitfab: api_key is empty: tracing is disabled. Provide a valid API key to enable tracing."
-        @enabled = false
-      end
-      @http_client = HttpClient.new(api_key:, service_url: @service_url)
+      # The user's on/off intent; effective enabled also requires a resolved key.
+      @explicitly_enabled = enabled
+      @strict = strict
+      # Cached only once a non-empty key is found, so an early resolve (before
+      # env loaded) can't poison a later one.
+      @resolved_api_key = nil
+      @api_key_warned = false
+      # The key is NOT read here. HttpClient gets a proc so the key is resolved
+      # at send time, after any env loading has run.
+      @http_client = HttpClient.new(api_key: -> { resolve_api_key }, service_url: @service_url)
       @pending_span_threads = {}
       @pending_span_mutex = Mutex.new
     end
 
+    # The configured API key (a proc is resolved on read). Reflects what was
+    # passed to the client; the ENV["BITFAB_API_KEY"] fallback applied during
+    # actual tracing is not surfaced here, and reading this never warns.
+    def api_key
+      @api_key_config.respond_to?(:call) ? @api_key_config.call : @api_key_config
+    end
+
+    # Effective tracing state, evaluated lazily: enabled only when not
+    # explicitly disabled AND a key resolves. Reading this resolves the key
+    # (and may emit the one-time empty-key warning), exactly as the first traced
+    # call would.
+    def enabled
+      tracing_enabled?
+    end
+
     # Replay historical traces through a method and create a test run.
     #
     # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
@@ -100,7 +119,10 @@ module Bitfab
     # Called by Traceable, not intended for direct use.
     def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:,
       mock_on_replay: false)
-      return yield unless @enabled
+      # Decide at CALL time, not construction. The key may be set after the
+      # client is built (env loaded later), so re-checking per call lets a
+      # late-resolved key take effect.
+      return yield unless tracing_enabled?
 
       # Span setup runs before the user's block. Tracing is a side-channel, so
       # if anything here raises (id generation, trace-state bookkeeping, a
@@ -321,6 +343,48 @@ module Bitfab
 
     private
 
+    # Resolve the API key lazily, the first time a span actually needs it.
+    #
+    # The key is intentionally NOT read at construction: a client built when a
+    # file is required can run before the app loads its env, so the key would be
+    # empty at construction even though it is set moments later. Resolution
+    # order: the configured value (a proc is called while still unresolved),
+    # then a fallback read of ENV["BITFAB_API_KEY"]. Once a non-empty key is
+    # found it is cached.
+    def resolve_api_key
+      return @resolved_api_key unless @resolved_api_key.nil?
+
+      from_config = @api_key_config.respond_to?(:call) ? @api_key_config.call : @api_key_config
+      candidate = if from_config && !from_config.to_s.strip.empty?
+        from_config
+      else
+        ENV["BITFAB_API_KEY"]
+      end
+      key = (candidate && !candidate.to_s.strip.empty?) ? candidate : nil
+      if key
+        @resolved_api_key = key
+        return key
+      end
+      if @strict
+        raise "Bitfab: no API key resolved. Set BITFAB_API_KEY or pass api_key: to " \
+          "Bitfab.configure. If a script loads env later, load it before the first " \
+          "traced call, or pass api_key: -> { ENV[\"BITFAB_API_KEY\"] }."
+      end
+      if @explicitly_enabled && !@api_key_warned
+        @api_key_warned = true
+        warn "Bitfab: api_key is empty: tracing is disabled. Provide a valid API key to enable tracing."
+      end
+      nil
+    end
+
+    # Whether tracing should run, decided lazily at call time. An explicit
+    # `enabled: false` short-circuits without ever touching the key.
+    def tracing_enabled?
+      return false unless @explicitly_enabled
+
+      !resolve_api_key.nil?
+    end
+
     # Build an Enumerator that drives `source`, restoring `[trace_id, span_id]`
     # on the iterating fiber so nested `bitfab_span` calls inside lazy / `each`
     # callbacks nest under the parent span. Yielded values are collected as the

data/lib/bitfab/http_client.rb

@@ -226,9 +226,12 @@ module Bitfab
     end
 
     def headers
+      # Resolve the key at request time, invoking the proc form if one was
+      # supplied (never read at construction).
+      key = @api_key.respond_to?(:call) ? @api_key.call : @api_key
       {
         "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@api_key}"
+        "Authorization" => "Bearer #{key}"
       }
     end
   end

data/lib/bitfab/replay.rb

@@ -266,7 +266,7 @@ module Bitfab
       # 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|
+      report = lambda do |result, source_trace_id, test_run_id|
         return unless on_progress
 
         progress_mutex.synchronize do
@@ -275,8 +275,19 @@ module Bitfab
           error.nil? ? (succeeded += 1) : (errored += 1)
           begin
             on_progress.call({
-              completed:, total:, succeeded:, errored:,
-              item: {trace_id: source_trace_id, error:, duration_ms: result[:duration_ms]}
+              test_run_id:, completed:, total:, succeeded:, errored:,
+              item: {
+                trace_id: source_trace_id,
+                replay_trace_id: result[:trace_id],
+                input: result[:input],
+                result: result[:result],
+                original_output: result[:original_output],
+                error:,
+                duration_ms: result[:duration_ms],
+                tokens: result[:tokens],
+                model: result[:model],
+                db_snapshot_ref: result[:db_snapshot_ref]
+              }
             })
           rescue => e
             warn "Bitfab: replay on_progress callback raised: #{e.message}"
@@ -288,7 +299,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, item["traceId"])
+          report.call(result, item["traceId"], test_run_id)
           result
         end
       else
@@ -306,7 +317,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, item["traceId"])
+              report.call(result, item["traceId"], test_run_id)
             end
           end
         end

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -59,8 +59,8 @@ module Bitfab
     # @example
     #   Bitfab.configure(api_key: ENV["BITFAB_API_KEY"])
     #
-    def configure(api_key:, service_url: nil, enabled: true)
-      @client = Client.new(api_key:, service_url:, enabled:)
+    def configure(api_key: nil, service_url: nil, enabled: true, strict: false)
+      @client = Client.new(api_key:, service_url:, enabled:, strict:)
     end
 
     # Returns the global client, raising if not configured.
@@ -110,10 +110,9 @@ module Bitfab
     # 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.
+    # (progress must not crash a run). The progress hash's item is forwarded
+    # verbatim through to_json, so the plugin sees the source trace id, local
+    # replay trace id, outputs, error, and duration of the item that just settled.
     #
     # @example
     #   Bitfab.client.replay(..., on_progress: Bitfab.method(:report_replay_progress))

metadata

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