bitfab 0.30.1 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a3e03384934c51dd57e27ac1213dca8f88b41ead5a0980c04bb10ba0ad464d8
-  data.tar.gz: da9c5574b00bd66ba481a78e0f1e0ce4f8e9336b35a7b2e9013498b475622237
+  metadata.gz: 6c30821c7a2d174dacfae3c40d838cf9b37d2f71e07be3b95aa385507cd26867
+  data.tar.gz: f041e1f63eedc9397c55d70f635ca75d0f365c7b6a970f943b6a282bcc4b10e9
 SHA512:
-  metadata.gz: 97f2755495103e92c94258f1763a1066bfc5a1944168e10dec1ad1e0bd24a58ca916791122cf3673f52326ca0d5b89b7ca8324071d40b6c408f3153167f6c95c
-  data.tar.gz: 61ba2d4b92cfa2c2665753319c6acf67dda2d48a547088d1ab47b2e9006835fe869185f3861d4e378f5c8e76167009f2580f385b5f6416467a24ae5b9dce8242
+  metadata.gz: 8427f0d34ca1fbafcbd1d8582da7d24fba552635e23fdc9cba0a5afe1198a3f0f712c1c7c3a25b4229abc441c8fc4057bc7bb284f6e830173213d4194410d699
+  data.tar.gz: e4472dd0149b0a604439da779a5bae825f8313b41f2270701ab77b1ee46baf286c636d6022ce0df65cbca995525a0a53418ba4f2d839db582be7a17be41c9c15

data/lib/bitfab/http_client.rb

@@ -118,7 +118,7 @@ module Bitfab
     #   same org and trace function or the server rejects the replay
     def start_replay(trace_function_key, limit, trace_ids: nil, code_change_description: nil,
       code_change_files: nil, experiment_group_id: nil, name: nil, include_db_branch_lease: false, dataset_id: nil,
-      grader_ids: nil)
+      grader_ids: nil, db_branch_settings: nil)
       payload = {
         "traceFunctionKey" => trace_function_key
       }
@@ -133,6 +133,7 @@ module Bitfab
       payload["includeDbBranchLease"] = true if include_db_branch_lease
       payload["datasetId"] = dataset_id unless dataset_id.nil?
       payload["graderIds"] = grader_ids unless grader_ids.nil?
+      payload["dbBranchSettings"] = db_branch_settings unless db_branch_settings.nil?
 
       # When DB branching is on, the server resolves a Neon preview branch per
       # item (snapshot + restore + poll), which can run several seconds each.

data/lib/bitfab/replay.rb

@@ -204,7 +204,8 @@ module Bitfab
         experiment_group_id:,
         include_db_branch_lease:,
         dataset_id:,
-        grader_ids:
+        grader_ids:,
+        db_branch_settings: db_branch_settings(environment)
       )
       test_run_id = replay_data["testRunId"]
       test_run_url = replay_data["testRunUrl"]
@@ -319,6 +320,32 @@ 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
+    # nothing was set. Dropping the key entirely keeps the request identical to
+    # what older SDKs send.
+    #
+    # Keys: :min_cu and :max_cu are the branch compute's autoscaling floor and
+    # 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
+      return nil if db_branch.nil? || db_branch.empty?
+
+      # Symbol or string keys, matching normalize_code_change_files: a hash
+      # assembled from JSON or YAML would otherwise be read as empty, leaving
+      # the branch on the mirror's defaults with no error to notice.
+      min_cu = db_branch[:min_cu] || db_branch["min_cu"]
+      max_cu = db_branch[:max_cu] || db_branch["max_cu"]
+      warmup_sql = db_branch[:warmup_sql] || db_branch["warmup_sql"]
+
+      settings = {}
+      settings["minCu"] = min_cu unless min_cu.nil?
+      settings["maxCu"] = max_cu unless max_cu.nil?
+      settings["warmupSql"] = warmup_sql unless warmup_sql.nil?
+      settings.empty? ? nil : settings
+    end
+
     # Auto-capture the code change to attach when the caller passed none. Lives
     # in replay() (the one call guaranteed to run on every replay) so it works no
     # matter how the replay was launched. Precedence: a BITFAB_CODE_CHANGE_PATH
@@ -599,9 +626,19 @@ module Bitfab
       # (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
-      # snapshot ref, or whose resolve failed server-side, arrive without a
-      # lease (env.active? is false for those).
+      # snapshot ref arrive without a lease (env.active? is false), and
+      # replaying those against the live database is correct.
       lease = include_db_branch_lease ? server_item["dbBranchLease"] : nil
+      # A resolve that was ATTEMPTED and failed is different: the caller asked
+      # for a branch, so running their method against live data would produce a
+      # result that looks valid and is not. Fail the item instead, loudly.
+      lease_error = include_db_branch_lease ? server_item["dbBranchLeaseError"] : nil
+      if lease_error
+        raise "Replay requested a database branch for trace #{original_trace_id} but it " \
+          "could not be resolved (#{lease_error["code"]}): #{lease_error["message"]}. " \
+          "The method was not run, because replaying it against the live database would " \
+          "produce a result that looks valid but did not use the historical data you asked for."
+      end
 
       span = http_client.get_external_span(original_span_id)
       item_data = extract_span_data(span)

data/lib/bitfab/replay_environment.rb

@@ -16,10 +16,40 @@ module Bitfab
   # 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
@@ -44,6 +74,13 @@ module Bitfab
       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)
@@ -95,6 +132,7 @@ module Bitfab
         expires_at: lease["expiresAt"],
         provider_console_url: lease["providerConsoleUrl"],
         read_only: lease["readOnly"],
+        region: lease["region"],
         trace_id:
       }
     end

data/lib/bitfab/version.rb

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

metadata

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