bitfab 0.22.1 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb8d7ab7e95fed00c067b1653c4d8271c1814b6a9d42bc8ffbb320596ac2190e
-  data.tar.gz: 6050620ec20d4172045e7a7c29930349e488cd886132cb54758ca98d789be34f
+  metadata.gz: 26ad3b53b9f3da35c01496ecc236ce0f5d27e7921761c7baca7654d1fb8de31e
+  data.tar.gz: e653a93c4bf8e5263b22a6114ebcc2a52db6cc3db6eecc7774cb7b6ed07c51c3
 SHA512:
-  metadata.gz: c94a534717dfbf682ca6d4f1fb6e9501fba8df1057bd6390457c4f561616a23bf53092bfc4bc8cc966f67037d1a7a9b8f2eadc4edff92645a99e2b0a9ffcf33b
-  data.tar.gz: 7e416c3b5af6248ada3bda42d56d2853d68792e7adcf3bb4a1e1af98b5b4740ee92cd7e25ba8c86fee0bc0b0acaa5acd102bb1d8e561d03d0e669d24de877048
+  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
@@ -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/version.rb

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