bitfab 0.17.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60fa4998513b5fa9f67950bf4abbbc253b324955732e3726531ca47856544ddb
-  data.tar.gz: ad45f27ff4c50a4a75329f48e6ba06f252eb74e425b1d19686b55f6c780ae6a0
+  metadata.gz: 9dd280a2cd6afdf47b2bbbf62508dd4918dccf42c83ed276845f592497168601
+  data.tar.gz: 224fc7cfe39e847f3bfd56e9876151ea356f7a8ad7bff66b529f9704ab360141
 SHA512:
-  metadata.gz: 1dd29ae11022f8cc0ad80b3d59e37d809843b85ab9cb48e0623afd01ee1a2d6b4e99e8ba91c996b7cad1acb589757ccf4a0291673a28d7a54eccffa098d5239e
-  data.tar.gz: efaf095342fee4995aa8d45c69773c7d268f5eb23e358606292c7dd3ba11a3958da7416606025f18c8c11b43c295b62ef0bcd80baf753c0070055ae0d3dcc0f3
+  metadata.gz: 4cba57762a9ae927ba34ac70fdd1d750d118a9f8f3cc47402f30d8a09c336337f27cef601f8b36e63140e01acaa410d1a58450f160cb1c3d7e7c2c5b1a198cb3
+  data.tar.gz: eaa0a0b2eed0c0f7c0e24a73e2128540c53a504e9a3dd4d6858355e8076aa2fa8a4913ea170b278ac1579c5e407d4333759e1bae345dbe575b9fa91b666275a1

data/lib/bitfab/client.rb

@@ -26,7 +26,7 @@ module Bitfab
       @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."
+        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)
@@ -87,7 +87,7 @@ module Bitfab
     end
 
     # Execute a block inside a span context, sending trace data on completion.
-    # Called by Traceable — not intended for direct use.
+    # 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
@@ -121,7 +121,7 @@ module Bitfab
       # 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.
+      # 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(
@@ -154,7 +154,7 @@ module Bitfab
       finalized = false
 
       finalize = lambda do |final_result, final_error|
-        # Never crash the host app due to span building/sending. Idempotent —
+        # Never crash the host app due to span building/sending. Idempotent:
         # only the first call sends the span. Subsequent calls (e.g. from the
         # enumerator wrapper after iteration completes) are no-ops.
         next if finalized
@@ -188,11 +188,27 @@ module Bitfab
             pending << span_thread if span_thread
             pending.each { |t| t.join(5) }
 
+            # Built AFTER the wrapped method finished (finalize runs at root
+            # span end), so :accessed reflects whether customer code obtained
+            # the branch URL during this item. nil (key omitted) when no
+            # lease was attached, so the server can distinguish "no branch"
+            # from "branch ignored".
+            lease = replay_ctx&.dig(:db_branch_lease)
+            db_snapshot_usage = if lease
+              {
+                neon_branch_id: lease["neonBranchId"],
+                snapshot_timestamp: lease["snapshotTimestamp"],
+                source_trace_id: replay_ctx[:source_bitfab_trace_id],
+                accessed: replay_ctx[:db_snapshot_accessed] == true
+              }
+            end
+
             completion_thread = send_trace_completion(
               trace_function_key:,
               trace_id:,
               started_at:,
-              ended_at:
+              ended_at:,
+              db_snapshot_usage:
             )
 
             # In replay, persistence is correctness: the replay runner joins
@@ -212,7 +228,7 @@ module Bitfab
             end
           end
         rescue Exception # rubocop:disable Lint/RescueException
-          # Silently ignore — user's result/exception takes priority
+          # Silently ignore: user's result/exception takes priority
           # Catches Exception (not just StandardError) to handle SystemStackError
           # from deeply nested serialization
         end
@@ -234,7 +250,7 @@ module Bitfab
 
       # If the wrapped block returned an Enumerator (lazy iteration via
       # `enum_for`, `to_enum`, `Enumerator.new`, `[...].lazy.map(...)`, etc.),
-      # the work hasn't actually run yet — the values are produced as the
+      # the work hasn't actually run yet: the values are produced as the
       # caller iterates. Without special handling we'd close the span here
       # with `result == <the Enumerator object>`, and any nested `bitfab_span`
       # calls inside the enumerator body would see an empty span stack and
@@ -264,7 +280,7 @@ module Bitfab
     # 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
-    # span output. The span is sent exactly once — when iteration finishes,
+    # span output. The span is sent exactly once: when iteration finishes,
     # raises, or the wrapper is `.close`d.
     def wrap_enumerator(source, trace_id:, span_id:, finalize:)
       span_entry = {trace_id:, span_id:}
@@ -296,7 +312,14 @@ module Bitfab
       raise ArgumentError, "Invalid span type '#{type}'. Must be one of: #{SPAN_TYPES.join(", ")}"
     end
 
-    def send_trace_completion(trace_function_key:, trace_id:, started_at:, ended_at:)
+    # db_snapshot_usage: replay DB branch usage record, present only when a
+    # lease was attached to the replay item. Serialized as `db_snapshot_usage`
+    # on the raw trace so the server can stamp the trace's metadata at ingest:
+    # { neon_branch_id:, snapshot_timestamp: (optional), source_trace_id:
+    # (optional), accessed: } with :accessed true if customer code obtained
+    # the branch URL and false if it ignored it. nil outside replay or when no
+    # lease was attached, in which case the key is omitted entirely.
+    def send_trace_completion(trace_function_key:, trace_id:, started_at:, ended_at:, db_snapshot_usage: nil)
       trace_state = TraceState.get(trace_id)
       trace_started_at = trace_state&.dig(:started_at) || started_at
 
@@ -318,6 +341,17 @@ module Bitfab
       if trace_state&.dig(:db_snapshot_ref)
         raw_trace["db_snapshot_ref"] = trace_state[:db_snapshot_ref]
       end
+      if db_snapshot_usage
+        usage = {"neon_branch_id" => db_snapshot_usage[:neon_branch_id]}
+        if db_snapshot_usage[:snapshot_timestamp]
+          usage["snapshot_timestamp"] = db_snapshot_usage[:snapshot_timestamp]
+        end
+        if db_snapshot_usage[:source_trace_id]
+          usage["source_trace_id"] = db_snapshot_usage[:source_trace_id]
+        end
+        usage["accessed"] = db_snapshot_usage[:accessed]
+        raw_trace["db_snapshot_usage"] = usage
+      end
 
       payload = {
         "type" => "sdk-function",
@@ -339,7 +373,7 @@ module Bitfab
       # Clean up trace state
       TraceState.delete(trace_id)
 
-      # Returned so the replay path can join it — trace completions must be
+      # Returned so the replay path can join it: trace completions must be
       # persisted before complete_replay builds the trace-ID mapping.
       completion_thread
     end
@@ -398,8 +432,8 @@ module Bitfab
     # non-root span under an active mock tree. Returns the call index this
     # invocation owns, or nil when there's nothing to advance (root span, or
     # no replay mock context). The counter MUST advance for every child span
-    # sharing the same (key, name) pair — including spans that won't be
-    # mocked — so unmarked spans don't silently shift subsequent marked
+    # sharing the same (key, name) pair (including spans that won't be
+    # mocked) so unmarked spans don't silently shift subsequent marked
     # spans' indices. Different (key, name) pairs have independent counters.
     def advance_mock_counter(replay_ctx, trace_function_key, span_name, is_root_span:)
       return nil if is_root_span
@@ -433,7 +467,7 @@ module Bitfab
       output_meta = mock_entry[:output_meta]
 
       # Type-preserving deserialization when the server included Ruby-side
-      # Marshal+Base64 metadata. Falls back to the JSON output silently — the
+      # Marshal+Base64 metadata. Falls back to the JSON output silently: the
       # spanTree endpoint currently returns superjson/jsonpickle-shaped meta,
       # which Ruby cannot reconstruct.
       if output_meta.is_a?(String) && !output_meta.empty?
@@ -484,13 +518,13 @@ module Bitfab
         @pending_span_threads[trace_id] << span_thread if span_thread && @pending_span_threads.key?(trace_id)
       end
     rescue Exception # rubocop:disable Lint/RescueException
-      # Never crash the host app — mocked span recording is best-effort
+      # Never crash the host app: mocked span recording is best-effort
     end
   end
 
   # Fluent wrapper bound to a single trace_function_key. Mirrors
   # `BitfabFunction` in the Python SDK and `BitfabFunction` in the TypeScript
-  # SDK — lets callers wrap multiple methods without repeating the key.
+  # SDK: lets callers wrap multiple methods without repeating the key.
   class BitfabFunction
     attr_reader :trace_function_key
 

data/lib/bitfab/replay.rb

@@ -6,9 +6,9 @@ require_relative "serialize"
 module Bitfab
   # Replay mock strategies. Mirrors the Python and TypeScript SDKs.
   #
-  # - "none"   — every child span runs real code (default)
-  # - "all"    — every child span returns its historical output
-  # - "marked" — only spans declared with mock_on_replay: true return historical
+  # - "none"   : every child span runs real code (default)
+  # - "all"    : every child span returns its historical output
+  # - "marked" : only spans declared with mock_on_replay: true return historical
   #              output; everything else runs real code
   MOCK_STRATEGIES = %w[none all marked].freeze
 
@@ -45,6 +45,16 @@ module Bitfab
       # The per-trace DB branch (resolved server-side) and the Bitfab trace ID
       # it belongs to ride on the context so ReplayEnvironment can read them
       # inside the replayed method.
+      #
+      # ReplayEnvironment also sets ctx[:db_snapshot_accessed] = true the
+      # first time customer code actually obtains the branch URL for this
+      # item (via +database_url+ or +snapshot+). Reported on the trace
+      # completion inside the +db_snapshot_usage+ record (its +accessed+
+      # field) so the server can distinguish "branch was provisioned and
+      # exposed" from "branch URL was actually consumed". Any future
+      # consumption path that hands the URL to customer code by other means
+      # (e.g. a process-isolated runner writing an env overlay) must also
+      # set this.
       ctx[:db_branch_lease] = db_branch_lease if db_branch_lease
       ctx[:source_bitfab_trace_id] = source_bitfab_trace_id if source_bitfab_trace_id
       Thread.current[REPLAY_CONTEXT_KEY] = ctx
@@ -135,7 +145,7 @@ module Bitfab
 
       # Every item joined its own trace-persistence threads (span uploads +
       # completion) in execute_item, so all replay traces are on the server
-      # by now — no flush needed, and complete_replay's trace-ID mapping is
+      # by now: no flush needed, and complete_replay's trace-ID mapping is
       # deterministic. complete_replay failures propagate: a missing mapping
       # means verdicts can't be persisted, which callers must hear about
       # loudly.
@@ -151,7 +161,7 @@ module Bitfab
       else
         # Map each item's locally-generated trace ID to the server's trace
         # row ID. A completed item with no mapping means its trace was sent
-        # but the server has no record — a nil trace_id blocks verdict
+        # but the server has no record: a nil trace_id blocks verdict
         # persistence and the Studio experiments view downstream, so this
         # must never be silent.
         #
@@ -244,8 +254,8 @@ module Bitfab
       metrics = extract_server_item_metrics(server_item)
       # The server resolves a Neon preview branch per item during /replay/start
       # (only when include_db_branch_lease was sent). Release it in the +ensure+
-      # below so any raise — span fetch, mock-tree build, or the replayed
-      # method — frees the Neon resource. Items whose source trace had no
+      # below so any raise (span fetch, mock-tree build, or the replayed
+      # method) frees the Neon resource. Items whose source trace had no
       # snapshot ref, or whose resolve failed server-side, arrive without a
       # lease (env.active? is false for those).
       lease = include_db_branch_lease ? server_item["dbBranchLease"] : nil
@@ -295,7 +305,7 @@ module Bitfab
     end
 
     # Delete the per-item Neon preview branch. Best-effort: a failure is warned
-    # but never raised — the server-side TTL janitor reaps orphans.
+    # but never raised: the server-side TTL janitor reaps orphans.
     def release_db_branch_lease(http_client, lease)
       neon_branch_id = lease["neonBranchId"]
       return unless neon_branch_id
@@ -308,7 +318,7 @@ module Bitfab
     # Walk the children of a root span tree node depth-first and build a
     # lookup keyed by "#{trace_function_key}:#{span_name}:#{call_index}".
     #
-    # The root node itself is excluded — at replay time the runtime root span
+    # The root node itself is excluded: at replay time the runtime root span
     # never queries the mock tree.
     #
     # The compound (key, name) match disambiguates same-key spans that come
@@ -316,7 +326,7 @@ module Bitfab
     # wrapped method shares trace_function_key but differs in span_name. The
     # counter is per-(key, name) pair so repeated same-name calls (including
     # recursion) still order by occurrence. Mirrors the Python and TypeScript
-    # SDKs after HVT-2078 — keying by trace_function_key alone caused the
+    # SDKs after HVT-2078: keying by trace_function_key alone caused the
     # wrong historical output for fluent-API span sets.
     def build_mock_tree(root)
       spans = {}
@@ -389,7 +399,7 @@ module Bitfab
       sdk_trace_id = SecureRandom.uuid
       # Collects the root span's persistence threads (span uploads + trace
       # completion). Joined below so this item's trace is on the server
-      # before run() calls complete_replay — otherwise the server's trace-ID
+      # before run() calls complete_replay: otherwise the server's trace-ID
       # mapping races the uploads and the item's trace_id comes back nil.
       pending_persistence = []
 
@@ -421,7 +431,7 @@ module Bitfab
       end
 
       # Wait for this item's trace (spans + completion) to be fully persisted
-      # before the item resolves. Runs on the error path too — a raising
+      # before the item resolves. Runs on the error path too: a raising
       # method still emits a root span whose trace must land before
       # complete_replay. Joins are bounded by the HTTP layer's own timeouts.
       pending_persistence.each(&:join)

data/lib/bitfab/replay_environment.rb

@@ -23,7 +23,9 @@ module Bitfab
     # The per-trace branch URL for the item currently being replayed.
     # Raises if read outside a replay item.
     def database_url
-      require_snapshot.fetch(:database_url)
+      snap = require_snapshot
+      mark_accessed
+      snap.fetch(:database_url)
     end
 
     # When the per-trace branch URL stops being valid. ISO-8601.
@@ -55,11 +57,25 @@ module Bitfab
     # Non-raising variant for callers that handle the inactive case. Returns a
     # symbol-keyed hash or nil.
     def snapshot
-      read_snapshot
+      snap = read_snapshot
+      mark_accessed if snap
+      snap
     end
 
     private
 
+    # Record on the replay context that customer code obtained the branch
+    # URL. Only +database_url+ and +snapshot+ count: +active?+, +read_only+
+    # and friends inspect the lease without exposing the connection string,
+    # so they don't prove the replayed code could have connected to the
+    # branch.
+    def mark_accessed
+      ctx = ReplayContext.current
+      return unless ctx && ctx[:db_branch_lease]
+
+      ctx[:db_snapshot_accessed] = true
+    end
+
     def read_snapshot
       ctx = ReplayContext.current
       return nil unless ctx
@@ -69,7 +85,7 @@ module Bitfab
 
       # Surface the Bitfab trace ID (what the customer sees in the dashboard),
       # falling back to the external trace ID only if the Bitfab ID is somehow
-      # absent — keeps replays from external sources working until the
+      # absent: keeps replays from external sources working until the
       # source-system path is fully wired.
       trace_id = ctx[:source_bitfab_trace_id] || ctx[:input_source_trace_id]
       return nil unless trace_id

data/lib/bitfab/version.rb

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

metadata

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