bitfab 0.9.0

data/lib/bitfab/http_client.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+require_relative "constants"
+require_relative "version"
+
+module Bitfab
+  class HttpClient
+    attr_reader :service_url
+
+    def initialize(api_key:, service_url: nil, timeout: 120)
+      @api_key = api_key
+      @service_url = (service_url || DEFAULT_SERVICE_URL).chomp("/")
+      @timeout = timeout
+    end
+
+    # Make a POST request to the Bitfab API.
+    # Returns parsed JSON response hash.
+    def request(endpoint, payload, timeout: nil, max_retries: 1, retry_delay: 0.1)
+      uri = URI("#{@service_url}#{endpoint}")
+      request_timeout = timeout || @timeout
+
+      last_error = nil
+
+      max_retries.times do |attempt|
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = request_timeout
+        http.read_timeout = request_timeout
+
+        req = Net::HTTP::Post.new(uri.path, headers)
+        req.body = JSON.generate(payload)
+
+        response = http.request(req)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Net::HTTPError.new("HTTP #{response.code}: #{response.body}", response)
+        end
+
+        result = JSON.parse(response.body)
+
+        if result["error"]
+          msg = result["error"]
+          msg = "#{msg} Configure it at: #{@service_url}#{result["url"]}" if result["url"]
+          raise StandardError, msg
+        end
+
+        return result
+      rescue => e
+        last_error = e
+        sleep(retry_delay) if attempt < max_retries - 1
+      end
+
+      raise last_error
+    end
+
+    # Send an external span in a background thread.
+    # Returns the thread for callers that need to await completion.
+    def send_external_span(payload)
+      merged = payload.merge("sdkVersion" => VERSION)
+
+      Bitfab._run_in_background do
+        request("/api/sdk/externalSpans", merged, timeout: 30)
+      end
+    end
+
+    # Make a GET request to the Bitfab API.
+    # Returns parsed JSON response hash.
+    def get(endpoint, timeout: nil)
+      uri = URI("#{@service_url}#{endpoint}")
+      request_timeout = timeout || @timeout
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = request_timeout
+      http.read_timeout = request_timeout
+
+      req = Net::HTTP::Get.new(uri.path, headers)
+      response = http.request(req)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Net::HTTPError.new("HTTP #{response.code}: #{response.body}", response)
+      end
+
+      result = JSON.parse(response.body)
+
+      if result["error"]
+        msg = result["error"]
+        msg = "#{msg} Configure it at: #{@service_url}#{result["url"]}" if result["url"]
+        raise StandardError, msg
+      end
+
+      result
+    end
+
+    # Start a replay session by fetching historical traces.
+    # Blocking call. Returns hash with testRunId, testRunUrl, and items array.
+    def start_replay(trace_function_key, limit, trace_ids: nil)
+      payload = {
+        "traceFunctionKey" => trace_function_key,
+        "limit" => limit
+      }
+      payload["traceIds"] = trace_ids if trace_ids
+
+      request("/api/sdk/replay/start", payload, timeout: 30)
+    end
+
+    # Fetch an external span by ID. Blocking GET request.
+    def get_external_span(span_id)
+      get("/api/sdk/externalSpans/#{span_id}", timeout: 30)
+    end
+
+    # Mark a replay test run as completed. Blocking call.
+    def complete_replay(test_run_id)
+      request("/api/sdk/replay/complete", {"testRunId" => test_run_id}, timeout: 30)
+    end
+
+    # Send an external trace (fire-and-forget in background thread).
+    def send_external_trace(payload)
+      merged = payload.merge("sdkVersion" => VERSION)
+
+      Bitfab._run_in_background do
+        request("/api/sdk/externalTraces", merged, timeout: 10)
+      end
+    end
+
+    private
+
+    def headers
+      {
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@api_key}"
+      }
+    end
+  end
+
+  # --- Background thread management ---
+
+  @pending_threads_mutex = Mutex.new
+  @pending_threads = []
+
+  class << self
+    # Run a block in a background thread with tracking.
+    # Returns the thread for callers that need to join on it.
+    def _run_in_background(&block)
+      thread = Thread.new do
+        block.call
+      rescue => e
+        begin
+          warn "Bitfab: Failed to send request: #{e.message}"
+        rescue
+          # Never crash the host app
+        end
+      ensure
+        @pending_threads_mutex.synchronize { @pending_threads.delete(Thread.current) }
+      end
+
+      @pending_threads_mutex.synchronize { @pending_threads << thread }
+      thread
+    end
+
+    # Wait for all pending background threads to complete.
+    def flush_traces(timeout: 30)
+      threads = @pending_threads_mutex.synchronize { @pending_threads.dup }
+      threads.each { |t| t.join(timeout) }
+    end
+  end
+
+  at_exit do
+    Bitfab.flush_traces(timeout: 2)
+  end
+end

data/lib/bitfab/replay.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "serialize"
+
+module Bitfab
+  # Thread-local replay context management.
+  module ReplayContext
+    module_function
+
+    def current
+      Thread.current[REPLAY_CONTEXT_KEY]
+    end
+
+    # Execute a block with replay context set on the current thread.
+    # The context is automatically cleared when the block completes.
+    def with_context(test_run_id:, input_source_span_id: nil)
+      previous = Thread.current[REPLAY_CONTEXT_KEY]
+      Thread.current[REPLAY_CONTEXT_KEY] = {
+        test_run_id:,
+        input_source_span_id:
+      }
+      yield
+    ensure
+      Thread.current[REPLAY_CONTEXT_KEY] = previous
+    end
+  end
+
+  # Replay historical traces through a traced method and create a test run.
+  module Replay
+    module_function
+
+    # Replay historical traces through a method and create a test run.
+    #
+    # Fetches the last N traces for the given trace function key, re-runs each
+    # through the provided receiver and method, and returns comparison data.
+    #
+    # @param client [Bitfab::Client] the Bitfab client instance
+    # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
+    # @param method_name [Symbol] the method to replay
+    # @param trace_function_key [String] the trace function key for this method
+    # @param limit [Integer] maximum number of traces to replay (default: 5)
+    # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
+    # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
+    # @return [Hash] with :items, :test_run_id, :test_run_url
+    def run(client, receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10)
+      http_client = client.instance_variable_get(:@http_client)
+
+      replay_data = http_client.start_replay(trace_function_key, limit, trace_ids:)
+      test_run_id = replay_data["testRunId"]
+      test_run_url = replay_data["testRunUrl"]
+      server_items = replay_data["items"] || []
+
+      result_items = if server_items.any?
+        process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency)
+      else
+        []
+      end
+
+      Bitfab.flush_traces
+
+      begin
+        http_client.complete_replay(test_run_id)
+      rescue => e
+        warn "Bitfab: Failed to complete replay: #{e.message}"
+      end
+
+      {
+        items: result_items,
+        test_run_id:,
+        test_run_url: "#{client.service_url}#{test_run_url}"
+      }
+    end
+
+    # Process all replay items, optionally in parallel using threads.
+    def process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency)
+      concurrency = max_concurrency || server_items.length
+
+      if concurrency <= 1
+        server_items.map { |item| process_single_item(http_client, item, receiver, method_name, test_run_id) }
+      else
+        results_mutex = Mutex.new
+        results = []
+        work_queue = server_items.each_with_index.to_a
+        work_mutex = Mutex.new
+
+        workers = [concurrency, server_items.length].min.times.map do
+          Thread.new do
+            loop do
+              item, idx = work_mutex.synchronize { work_queue.shift }
+              break unless item
+
+              result = process_single_item(http_client, item, receiver, method_name, test_run_id)
+              results_mutex.synchronize { results[idx] = result }
+            end
+          end
+        end
+
+        workers.each(&:join)
+        results.compact
+      end
+    end
+
+    # Fetch span data and execute a single replay item.
+    def process_single_item(http_client, server_item, receiver, method_name, test_run_id)
+      span = http_client.get_external_span(server_item["externalSpanId"])
+      item_data = extract_span_data(span)
+      execute_item(item_data, receiver, method_name, test_run_id, span["id"])
+    end
+
+    # Extract input/output data from an external span's rawData.
+    def extract_span_data(span)
+      raw_data = span["rawData"] || {}
+      span_data = raw_data["span_data"] || {}
+
+      {
+        "input" => span_data["input"],
+        "output" => span_data["output"],
+        "inputSerialized" => span_data["input_serialized"],
+        "outputSerialized" => span_data["output_serialized"]
+      }
+    end
+
+    # Execute a single replay item: deserialize inputs, call method with replay context.
+    def execute_item(item, receiver, method_name, test_run_id, input_source_span_id = nil)
+      args, kwargs = Serialize.deserialize_inputs(item)
+
+      fn_result = nil
+      fn_error = nil
+
+      ReplayContext.with_context(test_run_id:, input_source_span_id:) do
+        fn_result = if kwargs.empty?
+          receiver.send(method_name, *args)
+        else
+          receiver.send(method_name, *args, **kwargs)
+        end
+      rescue => e
+        fn_error = e.message
+      end
+
+      {
+        input: args,
+        result: fn_result,
+        original_output: item["output"],
+        error: fn_error
+      }
+    end
+  end
+end

data/lib/bitfab/serialize.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "time"
+
+module Bitfab
+  module Serialize
+    module_function
+
+    # Serialize a value for JSON storage (human-readable).
+    # Handles primitives, hashes, arrays, and objects with common conversion methods.
+    # Note: We intentionally avoid as_json here because it requires ActiveSupport,
+    # and we want to keep the SDK dependency-free (stdlib only).
+    def serialize_value(value)
+      case value
+      when nil, true, false, Integer, Float, String
+        value
+      when Hash
+        value.transform_keys(&:to_s).transform_values { |v| serialize_value(v) }
+      when Array
+        value.map { |v| serialize_value(v) }
+      when Set
+        value.map { |v| serialize_value(v) }
+      when Time, DateTime
+        value.iso8601(3)
+      when Date
+        value.to_s
+      when Symbol
+        value.to_s
+      else
+        if value.respond_to?(:to_h)
+          serialize_value(value.to_h)
+        elsif value.respond_to?(:to_a)
+          serialize_value(value.to_a)
+        else
+          value.to_s
+        end
+      end
+    end
+
+    # Serialize function inputs (args + kwargs) for span data (human-readable).
+    def serialize_inputs(args, kwargs = {})
+      serialized = args.map { |arg| serialize_value(arg) }
+      serialized << kwargs.transform_keys(&:to_s).transform_values { |v| serialize_value(v) } unless kwargs.empty?
+      serialized
+    end
+
+    # Marshal a value to a Base64-encoded string for Ruby-to-Ruby reconstruction.
+    # Handles arbitrary Ruby objects including custom classes.
+    #
+    # @param value [Object] any Ruby value
+    # @return [String, nil] Base64-encoded Marshal dump, or nil if marshalling fails
+    def marshal_value(value)
+      Base64.strict_encode64(Marshal.dump(value))
+    rescue TypeError, ArgumentError
+      # Some objects (Proc, IO, etc.) can't be marshalled
+      nil
+    end
+
+    # Unmarshal a Base64-encoded string back into a Ruby object.
+    #
+    # @param encoded [String] Base64-encoded Marshal dump
+    # @return [Object] the reconstructed Ruby object
+    def unmarshal_value(encoded)
+      Marshal.load(Base64.strict_decode64(encoded)) # rubocop:disable Security/MarshalLoad
+    end
+
+    # Deserialize replay inputs from a span's data into [args, kwargs].
+    #
+    # Prefers Marshal-serialized `inputSerialized` for type preservation,
+    # falls back to the raw `input` field.
+    #
+    # @param item [Hash] with "inputSerialized" and/or "input" keys
+    # @return [Array(Array, Hash)] positional args and keyword args
+    def deserialize_inputs(item)
+      input_serialized = item["inputSerialized"]
+      raw_input = item["input"]
+
+      if input_serialized.is_a?(String) && !input_serialized.empty?
+        begin
+          deserialized = unmarshal_value(input_serialized)
+          if deserialized.is_a?(Hash) && (deserialized.key?(:args) || deserialized.key?(:kwargs))
+            return [deserialized[:args] || [], deserialized[:kwargs] || {}]
+          end
+          return deserialized.nil? ? [[], {}] : [[deserialized], {}]
+        rescue
+          # Fall through to raw_input
+        end
+      end
+
+      if raw_input.is_a?(Array)
+        [raw_input, {}]
+      elsif raw_input.is_a?(Hash)
+        [[], raw_input.transform_keys(&:to_sym)]
+      elsif raw_input.nil?
+        [[], {}]
+      else
+        [[raw_input], {}]
+      end
+    end
+  end
+end

data/lib/bitfab/span_context.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Bitfab
+  # Handle to the current active span, allowing context to be added.
+  class CurrentSpan
+    def initialize(span_state)
+      @span_state = span_state
+    end
+
+    # The trace ID for the current span.
+    def trace_id
+      @span_state[:trace_id]
+    end
+
+    # Add a context entry to this span.
+    # The entire hash is pushed as a single entry in the contexts array.
+    # Context entries are accumulated - multiple calls add to the list.
+    #
+    # @param context [Hash] key-value pairs to add as a single context entry
+    def add_context(context)
+      return unless context.is_a?(Hash)
+
+      @span_state[:contexts] ||= []
+      @span_state[:contexts] << context
+    rescue
+      # Silently ignore - never crash the host app
+    end
+
+    # Set the prompt for this span.
+    # The prompt is stored in span_data.prompt. Calling multiple times
+    # overwrites the previous value.
+    #
+    # @param prompt [String] the prompt string to store
+    def set_prompt(prompt)
+      return unless prompt.is_a?(String)
+
+      @span_state[:prompt] = prompt
+    rescue
+      # Silently ignore - never crash the host app
+    end
+  end
+
+  # Handle to the current active trace, allowing trace-level context to be set.
+  class CurrentTrace
+    def initialize(trace_id)
+      @trace_id = trace_id
+    end
+
+    # Set the session ID for this trace.
+    # Session ID is used to group traces from the same user session.
+    # This is stored as a database column.
+    #
+    # @param session_id [String] the session ID to set
+    def set_session_id(session_id)
+      trace_state = get_or_create_trace_state
+      trace_state[:session_id] = session_id
+    rescue
+      # Silently ignore - never crash the host app
+    end
+
+    # Set metadata for this trace.
+    # Metadata is stored in the raw trace data. Subsequent calls merge with
+    # existing metadata, with later values taking precedence.
+    #
+    # @param metadata [Hash] key-value pairs to store as trace metadata
+    def set_metadata(metadata)
+      return unless metadata.is_a?(Hash)
+
+      trace_state = get_or_create_trace_state
+      trace_state[:metadata] = (trace_state[:metadata] || {}).merge(metadata)
+    rescue
+      # Silently ignore - never crash the host app
+    end
+
+    # Add a context entry to this trace.
+    # The entire hash is pushed as a single entry in the contexts array.
+    # Context entries are accumulated - multiple calls add to the list.
+    #
+    # @param context [Hash] key-value pairs to add as a single context entry
+    def add_context(context)
+      return unless context.is_a?(Hash)
+
+      trace_state = get_or_create_trace_state
+      trace_state[:contexts] ||= []
+      trace_state[:contexts] << context
+    rescue
+      # Silently ignore - never crash the host app
+    end
+
+    private
+
+    def get_or_create_trace_state
+      TraceState.get(@trace_id) || TraceState.create(@trace_id)
+    end
+  end
+
+  # Thread-local span stack for tracking nested spans.
+  # Each entry is a Hash with :trace_id and :span_id keys.
+  module SpanContext
+    STACK_KEY = :__bitfab_span_stack
+
+    module_function
+
+    def stack
+      Thread.current[STACK_KEY] ||= []
+    end
+
+    def current
+      stack.last
+    end
+
+    # Execute a block with a new span pushed onto the stack.
+    # The span is automatically popped when the block completes.
+    def with_span(trace_id:, span_id:)
+      entry = {trace_id:, span_id:}
+      stack.push(entry)
+      yield
+    ensure
+      stack.pop
+    end
+  end
+
+  # Global storage for trace states (trace_id -> state hash)
+  module TraceState
+    @states_mutex = Mutex.new
+    @states = {}
+
+    module_function
+
+    def get(trace_id)
+      @states_mutex.synchronize { @states[trace_id] }
+    end
+
+    def create(trace_id)
+      @states_mutex.synchronize do
+        @states[trace_id] ||= {
+          trace_id:,
+          started_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+        }
+      end
+    end
+
+    def delete(trace_id)
+      @states_mutex.synchronize { @states.delete(trace_id) }
+    end
+
+    def clear_all
+      @states_mutex.synchronize { @states.clear }
+    end
+  end
+end