bitfab 0.34.1 → 0.36.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e49c89f4d4084e04cc06422bf24853166d662ad16dcde10ff463b9b54994e44
-  data.tar.gz: 52554692415bcf2ae1cd985dc737d797e43c93d75bbb813e77ac28f157e10193
+  metadata.gz: e0b827ad6e9bca08b3025f9c2419290910999a5985705369e6375aee8091232c
+  data.tar.gz: e6e0a414013d3bee0efda22415430d9690fe537973a36e5f3dda540fcda3d5e4
 SHA512:
-  metadata.gz: ad413e1ed3c64b76fb1fa91e7911cb24d9b4d4e6be71528ca27cbd34e64af1b1a1d834a520c5e222259b0e7816be2b489c7ce33f6864771d32ece59c9b24e23a
-  data.tar.gz: c119e56f3b6c81251e05e40e011746e0ec8e33598dd383ceb0e5a4b4c2f04ad4cbfb067df5fe7f7d4eaa1daf293d2bc9d0d9d5999795a385b81086721c0fe0bd
+  metadata.gz: ee72cf5ed5c81ad34dbd4d980091523c90c7cb1d11fc716499ab5f604f1829f5653851350942b2cea6660e20e67c065ae8807e0778153a0ccf08a1397cc08491
+  data.tar.gz: 297efa6c3e5d9b1086536dd5e560168e9f9d4c638638b562a67d69ccb1c37253534da6447778032f93e186532f0a563eb7b7f41148eb6b9e0e2ac91c4ed2196e

data/lib/bitfab/client.rb

@@ -407,6 +407,7 @@ module Bitfab
               {
                 neon_branch_id: lease["neonBranchId"],
                 snapshot_timestamp: lease["snapshotTimestamp"],
+                region: lease["region"],
                 original_trace_id: replay_ctx[:source_bitfab_trace_id],
                 # Deprecated wire alias, kept so this SDK still reports usage
                 # against servers that predate the rename.
@@ -593,6 +594,9 @@ module Bitfab
         if db_snapshot_usage[:snapshot_timestamp]
           usage["snapshot_timestamp"] = db_snapshot_usage[:snapshot_timestamp]
         end
+        if db_snapshot_usage[:region]
+          usage["region"] = db_snapshot_usage[:region]
+        end
         if db_snapshot_usage[:original_trace_id]
           usage["original_trace_id"] = db_snapshot_usage[:original_trace_id]
           # Deprecated wire alias, kept so this SDK still reports usage

data/lib/bitfab/compress.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Bitfab
+  # Request body compression for Bitfab API requests.
+  module Compress
+    DISABLE_COMPRESSION_ENV = "BITFAB_DISABLE_COMPRESSION"
+
+    # Below this, compressing costs more than the saved bytes are worth, so
+    # small requests (function lookups, replay status polls, single-span
+    # batches) ride uncompressed.
+    MIN_COMPRESSED_BYTES = 8_192
+
+    module_function
+
+    # Returns the body to send and the Content-Encoding it carries, or nil when
+    # the body is sent as-is. Compression is best-effort: any failure sends the
+    # original body rather than dropping the span.
+    def encode_request_body(body)
+      return [body, nil] if ENV[DISABLE_COMPRESSION_ENV]
+      return [body, nil] if body.bytesize < MIN_COMPRESSED_BYTES
+
+      [Zlib.gzip(body), "gzip"]
+    rescue
+      [body, nil]
+    end
+  end
+end

data/lib/bitfab/http_client.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 require "uri"
 
+require_relative "compress"
 require_relative "constants"
 require_relative "serialize"
 require_relative "transport"
@@ -69,7 +70,9 @@ module Bitfab
         http.read_timeout = request_timeout
 
         req = Net::HTTP::Post.new(uri.path, headers)
-        req.body = body
+        encoded_body, content_encoding = Compress.encode_request_body(body)
+        req["Content-Encoding"] = content_encoding if content_encoding
+        req.body = encoded_body
 
         response = http.request(req)
 

data/lib/bitfab/payload_budget.rb

@@ -0,0 +1,152 @@
+require "json"
+
+module Bitfab
+  # The ceiling on a span's encoded payload, and the trimming that enforces it.
+  #
+  # A span's whole payload (input, output, contexts, prompt, metadata) ships as
+  # a single bitfab.payload string attribute, and the exporter drops any carrier
+  # that exceeds the per-request byte ceiling outright rather than trimming it.
+  # Capping each value on its own cannot prevent that: two values that each fit
+  # can still add up to an undeliverable span. So the budget is enforced on the
+  # encoded payload as a whole, and an oversized span ships with its largest
+  # fields stubbed instead of vanishing.
+  #
+  # The budget is measured on the *carrier* (the payload re-escaped into the
+  # OTLP attribute), not on the payload body, because the carrier is what the
+  # exporter weighs. Bounding the body instead leaves escape-heavy content to
+  # blow the request ceiling anyway: a body of escaped JSON, Windows paths, or
+  # regexes is nearly all backslashes, and every one of them doubles. Measured
+  # on a body sized exactly to a 2.4 MB cap, prose produced a 2.4 MB carrier but
+  # backslash-dense content produced 4.8 MB, which the exporter dropped.
+  #
+  # 2.8 MB leaves room beneath the 3 MB request ceiling for the span and request
+  # envelopes wrapped around the attribute.
+  module PayloadBudget
+    MAX_SPAN_CARRIER_BYTES = 2_800_000
+
+    # Span fields that identify the span rather than carry user data. Trimming
+    # one would leave a span that no longer says what it is, so they stay
+    # whatever the payload costs.
+    STRUCTURAL_SPAN_KEYS = ["name", "type", "function_name", "error_source"].freeze
+
+    module_function
+
+    # The byte length +body+ occupies once re-escaped as a JSON string value.
+    #
+    # +body+ is itself JSON text, so the first encode already replaced every
+    # control character with a \uXXXX sequence. Only " and \ are left to
+    # escape, and each costs exactly one more byte, which bounds the expansion
+    # at 2x and is what lets .fits_carrier_budget? skip this scan for all but
+    # the largest payloads.
+    def carrier_byte_length(body)
+      body.bytesize + body.count("\"\\\\") + 2
+    end
+
+    # Whether +body+ fits the carrier budget, measuring exactly only when the
+    # cheap bounds cannot already decide it. Escaping never shrinks the body and
+    # can at most double it, so anything under half the budget always fits and
+    # anything past the budget never does. Ordinary spans settle on the first
+    # comparison and never pay for the scan.
+    def fits_carrier_budget?(body)
+      size = body.bytesize
+      return true if size * 2 + 2 <= MAX_SPAN_CARRIER_BYTES
+      return false if size + 2 > MAX_SPAN_CARRIER_BYTES
+
+      carrier_byte_length(body) <= MAX_SPAN_CARRIER_BYTES
+    end
+
+    # Return a body within the budget, plus the fields that had to be stubbed.
+    def enforce(payload, body, &encode)
+      return [body, []] if fits_carrier_budget?(body)
+      return [body, []] unless payload.is_a?(Hash)
+
+      trimmed_payload, trimmed = trim(payload, &encode)
+      return [body, []] if trimmed_payload.nil?
+
+      mark_trimmed(trimmed_payload, trimmed)
+      [encode.call(trimmed_payload), trimmed]
+    rescue
+      [body, []]
+    end
+
+    # Stub the largest payload fields until the encoded body fits the budget.
+    # Returns [trimmed_payload, trimmed_keys], or nil when nothing could be
+    # trimmed: the caller then ships the oversized body and lets the exporter
+    # report the drop, which still beats silently emptying a span.
+    def trim(payload, &encode)
+      copy, containers = clone_trimmable(payload)
+      candidates = collect_candidates(containers)
+      return nil if candidates.empty?
+
+      trimmed = []
+      candidates.each do |container, key, size|
+        container[key] = "<unserializable: too_large_#{size}_bytes>"
+        trimmed << key
+        body = encode.call(copy)
+        return [copy, trimmed] if fits_carrier_budget?(body)
+      end
+      nil
+    end
+
+    # Copy the records holding user data so trimming never mutates the caller's.
+    def clone_trimmable(payload)
+      copy = payload.dup
+      containers = []
+
+      span_data = copy["span_data"] || copy[:span_data]
+      if span_data.is_a?(Hash)
+        clone = span_data.dup
+        copy[copy.key?("span_data") ? "span_data" : :span_data] = clone
+        containers << clone
+      end
+
+      raw_span = copy["rawSpan"] || copy[:rawSpan]
+      raw_span_data = raw_span.is_a?(Hash) ? (raw_span["span_data"] || raw_span[:span_data]) : nil
+      if raw_span_data.is_a?(Hash)
+        clone = raw_span_data.dup
+        raw_span_copy = raw_span.dup
+        raw_span_copy[raw_span.key?("span_data") ? "span_data" : :span_data] = clone
+        copy[copy.key?("rawSpan") ? "rawSpan" : :rawSpan] = raw_span_copy
+        containers << clone
+      end
+
+      # No span_data anywhere: a trace-level or otherwise unfamiliar payload.
+      # Trim its own fields rather than give up, so an oversized body still
+      # ships.
+      containers << copy if containers.empty?
+
+      [copy, containers]
+    end
+
+    def collect_candidates(containers)
+      candidates = containers.flat_map do |container|
+        container.filter_map do |key, value|
+          next if STRUCTURAL_SPAN_KEYS.include?(key.to_s) || value.nil?
+
+          begin
+            [container, key, JSON.generate(value).bytesize]
+          rescue
+            next
+          end
+        end
+      end
+      candidates.sort_by { |entry| -entry[2] }
+    end
+
+    # Record the trim in the payload's own errors, which is what the server
+    # reads to flag a trace as incomplete.
+    def mark_trimmed(payload, trimmed)
+      key = payload.key?(:errors) ? :errors : "errors"
+      existing = payload[key]
+      errors = existing.is_a?(Array) ? existing.dup : []
+      errors << {
+        "source" => "sdk",
+        "step" => "payload_budget",
+        "error" => "trimmed oversized field(s) to fit the " \
+          "#{MAX_SPAN_CARRIER_BYTES}-byte span carrier budget: " \
+          "#{trimmed.uniq.join(", ")}"
+      }
+      payload[key] = errors
+    end
+  end
+end

data/lib/bitfab/replay.rb

@@ -62,10 +62,12 @@ module Bitfab
       # (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
-      # 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.
+      # exposed" from "branch URL was actually consumed". Only an explicit
+      # +database_url+ read may set it. A path that hands the URL over by other
+      # means (e.g. a process-isolated runner writing an env overlay) must
+      # leave it alone: setting it there would make every such replay report
+      # accessed for free, and the flag would stop separating "branch was
+      # used" from "branch was offered".
       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

data/lib/bitfab/replay_branch.rb

@@ -17,9 +17,20 @@ module Bitfab
   # protocol term). Its useful fields are exposed directly here so customer code
   # never sees the word.
   class ReplayBranch
+    # The provider's own id for this branch, e.g. for correlating with its console.
+    attr_reader :neon_branch_id
+
+    # Env var name the customer's app reads, e.g. "DATABASE_URL".
+    attr_reader :env_key
+
     # When this branch's URL stops being valid. ISO-8601.
     attr_reader :expires_at
 
+    # The instant this branch is pinned to: the source trace's wall clock, read
+    # just before the traced method ran. Compare it against the trace you meant
+    # to replay to confirm the branch is the right point in history.
+    attr_reader :snapshot_timestamp
+
     # Deep link to the branch in the provider console, if available.
     attr_reader :provider_console_url
 
@@ -36,13 +47,28 @@ module Bitfab
 
     # 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"]
+      # Copy the lease wholesale minus the connection string, so a field the
+      # server starts sending reaches customer code without an SDK release.
+      # Everything set here must stay plain data: #database_url is the only
+      # member allowed to mark the branch as accessed.
+      # The internals are underscore-prefixed because the loop below writes an
+      # ivar per lease key: snake_case never emits a leading underscore, so no
+      # field the server invents can collide with them. A plain @fields would
+      # be clobbered mid-loop by a key named "fields", corrupting #as_json.
+      fields = {}
+      lease.each do |key, value|
+        next if key == "databaseUrl"
+
+        name = snake_case(key)
+        fields[name] = value
+        instance_variable_set(:"@#{name}", value)
+        define_singleton_method(name) { value } unless respond_to?(name)
+      end
       @trace_id = trace_id
-      @url = lease["databaseUrl"]
-      @context = context
+      fields["trace_id"] = trace_id
+      @_fields = fields.freeze
+      @_url = lease["databaseUrl"]
+      @_context = context
       freeze
     end
 
@@ -54,15 +80,39 @@ module Bitfab
     # 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
+      @_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}>"
+        "read_only=#{@read_only.inspect} " \
+        "snapshot_timestamp=#{@snapshot_timestamp.inspect}>"
+    end
+
+    # ActiveSupport gives every object a +to_json+ that serializes its instance
+    # variables, so under Rails a branch reaching a log line or an API response
+    # would carry the connection string and the whole replay context. Serialize
+    # the exposed fields only, the same set +inspect+ shows.
+    def as_json(_options = nil)
+      @_fields.dup
+    end
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+
+    private
+
+    # Two passes so a run of capitals stays one word: "dbURL" is "db_url", not
+    # "db_u_r_l". Must match the Python SDK's conversion exactly, or the same
+    # server field would arrive under different names in the two SDKs.
+    def snake_case(key)
+      key.gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
     end
   end
 end

data/lib/bitfab/serialize.rb

@@ -4,13 +4,17 @@ require "base64"
 require "json"
 require "time"
 
+require_relative "payload_budget"
+
 module Bitfab
   module Serialize
-    # Cap on serialized payload size. Walking arbitrary objects (e.g. an
-    # OpenAI client passed as a span input) can produce hundreds of KB to MB
-    # of useless internal state. Anything beyond this cap is replaced with a
-    # stub so the span still ships and the trace isn't dropped server-side.
-    MAX_SERIALIZED_BYTES = 512_000
+    # Cap on a single serialized value. Walking arbitrary objects can produce
+    # hundreds of KB to MB of useless internal state, so this is the cheap
+    # early-out that stops the walk before a pathological object is carried any
+    # further. It is deliberately the same number as the whole-span budget: one
+    # legitimately large value may use the entire budget, and PayloadBudget is
+    # what enforces the total once every field is in.
+    MAX_SERIALIZED_BYTES = PayloadBudget::MAX_SPAN_CARRIER_BYTES
 
     # Recursion guard for cyclic graphs and pathologically nested structures.
     MAX_SERIALIZE_DEPTH = 16
@@ -257,7 +261,28 @@ module Bitfab
     # the whole span/trace silently. A degraded payload warns loudly so the
     # trace isn't quietly left incomplete or not replayable.
     def safe_generate(payload)
-      JSON.generate(payload)
+      # Budget the value that was actually encoded, not the caller's original: a
+      # cyclic or otherwise non-encodable field cannot be sized (JSON.generate
+      # raises on it), so on the original graph the biggest field is skipped as
+      # a trim candidate and the oversized body ships anyway. The sanitized copy
+      # has those values already replaced with stubs, so every field is sizeable.
+      body, encoded = encode_unbounded(payload)
+      body, trimmed = PayloadBudget.enforce(encoded, body) { |value| encode_unbounded(value).first }
+      if trimmed.any?
+        Bitfab.warn_once(
+          "payload-over-budget",
+          "a span payload exceeded the #{PayloadBudget::MAX_SPAN_CARRIER_BYTES}-byte carrier budget; its " \
+          "largest field(s) (#{trimmed.uniq.join(", ")}) were replaced with placeholders " \
+          "so the span still ships. The span is incomplete and may not be replayable."
+        )
+      end
+      body
+    end
+
+    # Returns [body, encoded_value] where encoded_value is what the body was
+    # generated from: the payload itself, or its sanitized copy.
+    def encode_unbounded(payload)
+      [JSON.generate(payload), payload]
     rescue => e
       Bitfab.warn_once(
         "request-body-stubbed",
@@ -268,10 +293,12 @@ module Bitfab
       )
 
       begin
-        JSON.generate(sanitize_payload(payload))
+        sanitized = sanitize_payload(payload)
+        [JSON.generate(sanitized), sanitized]
       rescue
         # Truly pathological. Still never drop silently: send a marker body.
-        JSON.generate({"error" => "payload_serialize_failed"})
+        marker = {"error" => "payload_serialize_failed"}
+        [JSON.generate(marker), marker]
       end
     end
 

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -5,6 +5,7 @@ require "json"
 require_relative "bitfab/version"
 require_relative "bitfab/constants"
 require_relative "bitfab/warn_once"
+require_relative "bitfab/payload_budget"
 require_relative "bitfab/serialize"
 require_relative "bitfab/db_snapshot"
 require_relative "bitfab/span_context"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.34.1
+  version: 0.36.1
 platform: ruby
 authors:
 - Harvest Team
@@ -138,11 +138,13 @@ files:
 - README.md
 - lib/bitfab.rb
 - lib/bitfab/client.rb
+- lib/bitfab/compress.rb
 - lib/bitfab/constants.rb
 - lib/bitfab/db_snapshot.rb
 - lib/bitfab/http_client.rb
 - lib/bitfab/mock_override.rb
 - lib/bitfab/otel.rb
+- lib/bitfab/payload_budget.rb
 - lib/bitfab/replay.rb
 - lib/bitfab/replay_branch.rb
 - lib/bitfab/serialize.rb