bitfab 0.34.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 897fb65140b86333bb5012746e570c785560c7865cd79da1e872e4ec567fada2
-  data.tar.gz: 26b89a73668a0f86746a349c8f57fe39317f069dbab04dd8731ff91950d24a49
+  metadata.gz: 1b5fdfbac8e62c59768ba554cd7c68b6fb7de3f1a37befd01a66cc6097821499
+  data.tar.gz: 31bb825d1fcde3c946c5467bb6e1ccbd56816815b38ba4f3eb5395bdb5061907
 SHA512:
-  metadata.gz: cb837f5a94d68391c0b25ac1bc073cba636816270abd623b825b59a2a3d8f387ac67a49aaef93aebcc3201ad24dbe4ef9f4d4738955d5db5387181eb1f94ee68
-  data.tar.gz: 0b609be82dca49043083bf966b52b01466f8252abe15b243e4d2ac6a3ea06d5238fb5fdf7b88e7a2c1be22fa4c36b06425baa2261a62ffed6967b5e8c86a8150
+  metadata.gz: efd78672cf98417507533b22bc0d4783ad7c29a18c4e9f419d95e328831275c26b4d15888642f07e19cd7a85b62babe55e223576d6a4885228fea4243ab84607
+  data.tar.gz: 83dc9683122eefbe92fc747d783fb81351acc6ccef94e1c31f5ae2b391adac9d775832d9f56818cde2541817a4b8cde475cda44021b93a5f23bcbac9a010904a

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/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
@@ -57,7 +61,17 @@ module Bitfab
       end
 
       case value
-      when nil, true, false, Integer, Float, String
+      when Float
+        # JSON has no NaN/Infinity literal, so Ruby's generator raises on one.
+        # Left unstubbed it kills the encode for the whole batch, not just this
+        # span. Mirrors the Python SDK's non_finite_float placeholder.
+        if value.finite?
+          value
+        else
+          dropped << "non_finite_float"
+          "<unserializable: non_finite_float>"
+        end
+      when nil, true, false, Integer, String
         value
       when Hash
         value.each_with_object({}) do |(k, v), acc|
@@ -247,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",
@@ -258,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.0"
+  VERSION = "0.36.0"
 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.0
+  version: 0.36.0
 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