bitfab 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c30821c7a2d174dacfae3c40d838cf9b37d2f71e07be3b95aa385507cd26867
-  data.tar.gz: f041e1f63eedc9397c55d70f635ca75d0f365c7b6a970f943b6a282bcc4b10e9
+  metadata.gz: fa66ab7393ccfdd162cdeaecee49c7b18efa601244afc8d7830568602968efd2
+  data.tar.gz: 29312e2278ad9a39033f82f01a45c20ef12bee1f3ac4b6140c94b22f0ae9dc48
 SHA512:
-  metadata.gz: 8427f0d34ca1fbafcbd1d8582da7d24fba552635e23fdc9cba0a5afe1198a3f0f712c1c7c3a25b4229abc441c8fc4057bc7bb284f6e830173213d4194410d699
-  data.tar.gz: e4472dd0149b0a604439da779a5bae825f8313b41f2270701ab77b1ee46baf286c636d6022ce0df65cbca995525a0a53418ba4f2d839db582be7a17be41c9c15
+  metadata.gz: dda0002685836ac6e381ecbf37430950df3fa7df9bad695e80803bb1c0da432885027be571feb02ba571adbc4c98a927e1a67eb910f3c8784c0bfde18e4b4f75
+  data.tar.gz: 183c49cc2d9ed286d3ea94e5505e09d6efdfe1cd2e5d73c31e1d504029643745bb796029395c70dc8afc1b2f165b3ecb84d2798933b806d0c00bd8b483d7a94e

data/lib/bitfab/client.rb

@@ -105,6 +105,11 @@ module Bitfab
     #   first matching override wins. Per-call overrides take precedence over
     #   those registered via register_mock_override, and both take precedence
     #   over the base mock strategy. The root span is never overridden.
+    # @param db_branch [Hash, nil] passing it at all turns database branching
+    #   on, so +{}+ enables it with the mirror project's own sizing. Keys
+    #   +:min_cu+/+:max_cu+ size the branch compute in Neon Compute Units and
+    #   +:warmup_sql+ warms its cache. Read the resolved branch inside the
+    #   replayed method with +Bitfab.current_replay_branch+.
     # @param on_progress [#call, nil] optional callback invoked once per item as
     #   it finishes, with a running-totals hash { completed:, total:, succeeded:,
     #   errored: }. Use it to render replay progress (e.g. a terminal progress
@@ -114,12 +119,12 @@ module Bitfab
     # @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,
       name: nil, code_change_description: nil, code_change_files: nil, experiment_group_id: nil, dataset_id: nil, grader_ids: nil, mock: "marked",
-      adapt_inputs: nil, mock_override: nil, environment: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
       Replay.run(
         self, receiver, method_name,
         trace_function_key:, limit:, trace_ids:, name:, max_concurrency:,
         code_change_description:, code_change_files:, experiment_group_id:, dataset_id:, grader_ids:, mock:, adapt_inputs:,
-        mock_override:, environment:,
+        mock_override:, db_branch:,
         on_progress:
       )
     end

data/lib/bitfab/replay.rb

@@ -58,12 +58,12 @@ module Bitfab
         ctx[:fetch_span_output] = fetch_span_output if fetch_span_output
       end
       # 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.
+      # it belongs to ride on the context so ReplayBranch 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
+      # ReplayBranch also sets ctx[:db_snapshot_accessed] = true the first
+      # time customer code actually obtains the branch URL for this item
+      # (via +database_url+). 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
@@ -120,6 +120,12 @@ module Bitfab
     #   source_trace_id/source_span_id aliases), and returns [new_args, new_kwargs].
     #   Runs per item inside the same rescue as the method, so a raising adapter
     #   sets that item's :error rather than crashing the run.
+    # @param db_branch [Hash, nil] passing it at all turns database branching
+    #   on, so +{}+ enables it with the mirror project's own sizing. Keys
+    #   +:min_cu+/+:max_cu+ are the branch compute's autoscaling floor and
+    #   ceiling in Neon Compute Units, and +:warmup_sql+ warms the branch's
+    #   cache before the replayed method sees it. Read the resolved branch
+    #   inside the method with +Bitfab.current_replay_branch+.
     # @param on_progress [#call, nil] optional callback invoked once per item as
     #   it finishes, with a running-totals hash { completed:, total:, succeeded:,
     #   errored:, item: } where item is { trace_id:, original_trace_id:,
@@ -136,7 +142,7 @@ module Bitfab
     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, grader_ids: nil, mock: "marked",
-      adapt_inputs: nil, mock_override: nil, environment: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
       unless MOCK_STRATEGIES.include?(mock.to_s)
         raise ArgumentError, "Invalid mock strategy '#{mock}'. Must be one of: #{MOCK_STRATEGIES.join(", ")}"
       end
@@ -179,7 +185,7 @@ module Bitfab
       # the count), so it's omitted from the request entirely.
       effective_limit = trace_ids ? nil : (limit || 5)
 
-      include_db_branch_lease = !environment.nil?
+      include_db_branch_lease = !db_branch.nil?
 
       # An explicit code change always wins; only when the caller passed neither
       # field do we fall back to the payload the replay wrapper captured from git
@@ -205,7 +211,7 @@ module Bitfab
         include_db_branch_lease:,
         dataset_id:,
         grader_ids:,
-        db_branch_settings: db_branch_settings(environment)
+        db_branch_settings: db_branch_settings(db_branch)
       )
       test_run_id = replay_data["testRunId"]
       test_run_url = replay_data["testRunUrl"]
@@ -320,7 +326,7 @@ module Bitfab
     CC_MAX_FILE_BYTES = 500_000
     CC_MAX_TOTAL_BYTES = 2_000_000
 
-    # Convert the environment's branch options to the wire shape, or nil when
+    # Convert the caller's +db_branch+ options to the wire shape, or nil when
     # nothing was set. Dropping the key entirely keeps the request identical to
     # what older SDKs send.
     #
@@ -328,8 +334,7 @@ module Bitfab
     # ceiling in Neon Compute Units (equal values pin the size, keeping items
     # comparable); :warmup_sql is appended to the branch's readiness check so it
     # warms the cache before the replayed function sees the lease.
-    def db_branch_settings(environment)
-      db_branch = environment&.db_branch
+    def db_branch_settings(db_branch)
       return nil if db_branch.nil? || db_branch.empty?
 
       # Symbol or string keys, matching normalize_code_change_files: a hash

data/lib/bitfab/replay_branch.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Bitfab
+  # The database branch a single replay item runs against.
+  #
+  # +Bitfab.current_replay_branch+ hands you one inside a replayed method when
+  # the source trace carried a DB snapshot reference and the Bitfab service
+  # resolved a branch from it. Outside a replay item, or when no branch was
+  # resolved, that reader returns nil and your code keeps reading
+  # +ENV["DATABASE_URL"]+ the normal way.
+  #
+  # Immutable and scoped to one item: the reader builds it from the thread-local
+  # replay context, so parallel replay items each see their own branch and no
+  # lease state lives on a long-lived object.
+  #
+  # Internally the resolved per-item state is a DB branch lease (the SDK/server
+  # protocol term). Its useful fields are exposed directly here so customer code
+  # never sees the word.
+  class ReplayBranch
+    # When this branch's URL stops being valid. ISO-8601.
+    attr_reader :expires_at
+
+    # Deep link to the branch in the provider console, if available.
+    attr_reader :provider_console_url
+
+    # True if the branch is read-only. Use it to skip write operations during
+    # replay when the provider returned a read-only lease.
+    attr_reader :read_only
+
+    # The branch's region, e.g. "aws-us-east-1". A compute runs in its project's
+    # region, so a replay runner elsewhere pays that round trip on every query.
+    attr_reader :region
+
+    # The historical trace ID that produced the input for this replay item.
+    attr_reader :trace_id
+
+    # Built by Bitfab.current_replay_branch; never constructed by callers.
+    def initialize(lease, trace_id, context)
+      @expires_at = lease["expiresAt"]
+      @provider_console_url = lease["providerConsoleUrl"]
+      @read_only = lease["readOnly"]
+      @region = lease["region"]
+      @trace_id = trace_id
+      @url = lease["databaseUrl"]
+      @context = context
+      freeze
+    end
+
+    # Connection string for this item's branch. Point your database client at it
+    # instead of the live database for the duration of the replayed call.
+    #
+    # Reading it records on the trace that the replayed code obtained the branch
+    # URL, which is what separates "a branch was provisioned" from "the branch
+    # was actually used". The other readers inspect the lease without exposing
+    # the connection string, so they deliberately do not record anything.
+    def database_url
+      @context[:db_snapshot_accessed] = true
+      @url
+    end
+
+    # Redact the connection string so a logged or inspected branch cannot leak it.
+    def inspect
+      "#<Bitfab::ReplayBranch trace_id=#{@trace_id.inspect} " \
+        "expires_at=#{@expires_at.inspect} region=#{@region.inspect} " \
+        "read_only=#{@read_only.inspect}>"
+    end
+  end
+end

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -11,7 +11,7 @@ require_relative "bitfab/span_context"
 require_relative "bitfab/http_client"
 require_relative "bitfab/mock_override"
 require_relative "bitfab/replay"
-require_relative "bitfab/replay_environment"
+require_relative "bitfab/replay_branch"
 require_relative "bitfab/client"
 require_relative "bitfab/traceable"
 
@@ -102,6 +102,34 @@ module Bitfab
       CurrentSpan.new(entry)
     end
 
+    # Get the database branch the current replay item is running against.
+    #
+    # Call this from inside a method being replayed with
+    # +client.replay(db_branch: ...)+ and point your database client at
+    # +branch.database_url+ so the replay reads the data as it was at trace
+    # time:
+    #
+    #   branch = Bitfab.current_replay_branch
+    #   url = branch ? branch.database_url : ENV["DATABASE_URL"]
+    #
+    # @return [ReplayBranch, nil] nil outside a replay item, and for an item
+    #   whose source trace carried no DB snapshot reference
+    def current_replay_branch
+      ctx = ReplayContext.current
+      return nil unless ctx
+
+      lease = ctx[:db_branch_lease]
+      return nil unless lease
+
+      # Surface the Bitfab trace ID (what the customer sees in the dashboard),
+      # not the external one. Falling back to the external ID keeps replays from
+      # external sources working until that path is fully wired.
+      trace_id = ctx[:source_bitfab_trace_id] || ctx[:input_source_trace_id]
+      return nil unless trace_id
+
+      ReplayBranch.new(lease, trace_id, ctx)
+    end
+
     # Get a handle to the current active trace.
     #
     # Call this from inside a traced method to get a trace handle that allows

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.33.0
 platform: ruby
 authors:
 - Harvest Team
@@ -123,7 +123,7 @@ files:
 - lib/bitfab/http_client.rb
 - lib/bitfab/mock_override.rb
 - lib/bitfab/replay.rb
-- lib/bitfab/replay_environment.rb
+- lib/bitfab/replay_branch.rb
 - lib/bitfab/serialize.rb
 - lib/bitfab/span_context.rb
 - lib/bitfab/traceable.rb

data/lib/bitfab/replay_environment.rb

@@ -1,148 +0,0 @@
-# frozen_string_literal: true
-
-module Bitfab
-  # Per-trace environment exposed to customer code during replay.
-  #
-  # The customer instantiates one +ReplayEnvironment+ and passes it to
-  # +client.replay(environment: ...)+. Inside the replayed method they read
-  # +env.database_url+ (and friends) to pick up the per-trace branch URL the
-  # Bitfab service resolved from the source trace's snapshot reference.
-  #
-  # Outside replay, reading +env.database_url+ raises. Customer code uses the
-  # env only on the replay path; live request code keeps reading
-  # +ENV["DATABASE_URL"]+ the normal way.
-  #
-  # Concurrency-safe: the readers resolve through the thread-local replay
-  # context, so each in-flight replay item sees its own per-trace values even
-  # when the SDK runs items across worker threads.
-  #
-  # The constructor takes how each branch should be sized and warmed. That
-  # lives here rather than on the replay arguments because the settings only
-  # mean anything for a replay that has an environment.
-  #
-  # Internally the resolved per-item state is a DB branch lease (the SDK <->
-  # server protocol term). We expose its useful fields directly here so
-  # customer code never sees the word.
-  class ReplayEnvironment
-    # The branch settings this environment was constructed with, as a
-    # symbol-keyed hash, readable anywhere. Every other reader reports the
-    # lease the server resolved and is therefore replay-only.
-    attr_reader :db_branch
-
-    # @param min_cu [Numeric, nil] autoscaling floor for the branch's compute,
-    #   in Neon Compute Units (0.25 to 56). Omit to keep the mirror project's
-    #   own default. Raise it when the mirror is provisioned smaller than the
-    #   database it stands in for, so replay latency reflects your code rather
-    #   than a cold, undersized branch.
-    # @param max_cu [Numeric, nil] autoscaling ceiling, in Neon Compute Units.
-    #   Equal to +min_cu+ pins the size, which keeps items comparable:
-    #   otherwise a later item can run against an endpoint that already scaled
-    #   up and post a better number for the same code.
-    # @param warmup_sql [String, nil] SQL that warms the branch's cache. The
-    #   server appends it to the branch's readiness check, so it runs BEFORE
-    #   your method sees the lease and its time is not charged to the replayed
-    #   call. Invalid SQL fails the lease rather than silently leaving the
-    #   branch cold.
-    def initialize(min_cu: nil, max_cu: nil, warmup_sql: nil)
-      @db_branch = {}
-      @db_branch[:min_cu] = min_cu unless min_cu.nil?
-      @db_branch[:max_cu] = max_cu unless max_cu.nil?
-      @db_branch[:warmup_sql] = warmup_sql unless warmup_sql.nil?
-    end
-
-    # The per-trace branch URL for the item currently being replayed.
-    # Raises if read outside a replay item.
-    def database_url
-      snap = require_snapshot
-      mark_accessed
-      snap.fetch(:database_url)
-    end
-
-    # When the per-trace branch URL stops being valid. ISO-8601.
-    def expires_at
-      require_snapshot.fetch(:expires_at)
-    end
-
-    # Deep link to the branch in the provider console, if available.
-    def provider_console_url
-      require_snapshot[:provider_console_url]
-    end
-
-    # True if the branch is read-only. Customer code can use this to skip write
-    # operations during replay when the provider returned a read-only lease.
-    def read_only
-      require_snapshot[:read_only]
-    end
-
-    # The branch's region, e.g. "aws-us-east-1". A compute runs in its
-    # project's region, so a replay runner elsewhere pays that round trip on
-    # every query.
-    def region
-      require_snapshot[:region]
-    end
-
-    # The historical trace ID that produced the input for this replay item.
-    def trace_id
-      require_snapshot.fetch(:trace_id)
-    end
-
-    # True when read inside a replay item that has a resolved branch.
-    def active?
-      !read_snapshot.nil?
-    end
-
-    # Non-raising variant for callers that handle the inactive case. Returns a
-    # symbol-keyed hash or nil.
-    def 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
-
-      lease = ctx[:db_branch_lease]
-      return nil unless lease
-
-      # 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
-      # source-system path is fully wired.
-      trace_id = ctx[:source_bitfab_trace_id] || ctx[:input_source_trace_id]
-      return nil unless trace_id
-
-      {
-        database_url: lease["databaseUrl"],
-        expires_at: lease["expiresAt"],
-        provider_console_url: lease["providerConsoleUrl"],
-        read_only: lease["readOnly"],
-        region: lease["region"],
-        trace_id:
-      }
-    end
-
-    def require_snapshot
-      snap = read_snapshot
-      return snap if snap
-
-      raise "ReplayEnvironment accessed outside of a replay item. Pass it to " \
-        "client.replay(environment: ...) and only read it inside the replayed method."
-    end
-  end
-end