bitfab 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3286f80b5a55bff760f454480b1a3662fdf984174ee65d6f195dcbca5d456ed
-  data.tar.gz: d1d8bc8e244075f56cc6c06d42dae614da95b4531ea8bafc21de2b84b1d2526a
+  metadata.gz: 26ad3b53b9f3da35c01496ecc236ce0f5d27e7921761c7baca7654d1fb8de31e
+  data.tar.gz: e653a93c4bf8e5263b22a6114ebcc2a52db6cc3db6eecc7774cb7b6ed07c51c3
 SHA512:
-  metadata.gz: 2ffbf4c36e417d4bf391eb9509a0136bc29dda1e54e191c84b51a59c400821fe7c21dbb796d272eaaca30f72502160d3aa8cb93efe1159304778422ac70ca9c1
-  data.tar.gz: 2dac975acb96571c6e7303ac7632cf3b099f3884ce3bf7f499dbfb35c71c357674868210906ebc6864dabb3a6645b7f82e41b4b8559553ab2a93304e2d106871
+  metadata.gz: 7c31a1ffd2e8be0cd31fd94941479351176823eabeadf453972bd493aeadbbc7de97002f484787a6e009024a42a6ed1e3a8fc99ded4b94eb3fd842d6e03772e9
+  data.tar.gz: 01ee591f9c3a51254abc101229ba261bc054acd02bfe7c67471367fd8cb0cc2fa015a1c1affc149358caf7dc5af98c7ea4f5351973153b60c6983befbc4d7ac7

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
@@ -68,11 +87,11 @@ module Bitfab
     #   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",
+      name: nil, code_change_description: nil, code_change_files: nil, experiment_group_id: nil, dataset_id: nil, mock: "none",
       adapt_inputs: nil, environment: nil, on_progress: nil)
       Replay.run(
         self, receiver, method_name,
-        trace_function_key:, limit:, trace_ids:, max_concurrency:,
+        trace_function_key:, limit:, trace_ids:, name:, max_concurrency:,
         code_change_description:, code_change_files:, experiment_group_id:, dataset_id:, mock:, adapt_inputs:, environment:,
         on_progress:
       )
@@ -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

@@ -107,10 +107,12 @@ module Bitfab
     #   each as { path:, before:, after: } (use "" for new/deleted files)
     # @param experiment_group_id [String, nil] optional UUID grouping multiple
     #   replay runs into a single experiment batch
+    # @param name [String, nil] optional display name for the resulting
+    #   experiment/test run
     # @param dataset_id [String, nil] optional UUID of the dataset this replay
     #   runs against, stored on the resulting experiment for durable attribution
     def start_replay(trace_function_key, limit, trace_ids: nil, code_change_description: nil,
-      code_change_files: nil, experiment_group_id: nil, include_db_branch_lease: false, dataset_id: nil)
+      code_change_files: nil, experiment_group_id: nil, name: nil, include_db_branch_lease: false, dataset_id: nil)
       payload = {
         "traceFunctionKey" => trace_function_key
       }
@@ -118,6 +120,7 @@ module Bitfab
       # already determines the count), so it's omitted when nil.
       payload["limit"] = limit unless limit.nil?
       payload["traceIds"] = trace_ids if trace_ids
+      payload["name"] = name unless name.nil?
       payload["codeChangeDescription"] = code_change_description unless code_change_description.nil?
       payload["codeChangeFiles"] = normalize_code_change_files(code_change_files) unless code_change_files.nil?
       payload["experimentGroupId"] = experiment_group_id unless experiment_group_id.nil?
@@ -223,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

@@ -82,6 +82,7 @@ module Bitfab
     #   Ignored when trace_ids is passed (with a warning): an explicit ID list
     #   already determines how many traces replay.
     # @param trace_ids [Array<String>, nil] optional list of trace IDs to replay (max 100)
+    # @param name [String, nil] optional display name for the resulting experiment/test run
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
     # @param code_change_description [String, nil] optional rationale for the
     #   code change being tested in this replay (stored on the experiment)
@@ -109,8 +110,9 @@ module Bitfab
     #   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",
+    def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: 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, on_progress: nil)
       unless MOCK_STRATEGIES.include?(mock.to_s)
         raise ArgumentError, "Invalid mock strategy '#{mock}'. Must be one of: #{MOCK_STRATEGIES.join(", ")}"
@@ -153,6 +155,7 @@ module Bitfab
         trace_function_key,
         effective_limit,
         trace_ids:,
+        name:,
         code_change_description:,
         code_change_files:,
         experiment_group_id:,

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.22.0"
+  VERSION = "0.23.0"
 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.

metadata

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