openai-compatible-errors 0.1.0

data/lib/openai_compatible_errors/sse.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenAICompatibleErrors
+  StreamState = Struct.new(:events_seen, :malformed_events, :has_output,
+                           :protocol, :termination, :error, keyword_init: true) do
+    def initialize(events_seen: 0, malformed_events: 0, has_output: false,
+                   protocol: :unknown, termination: :open, error: nil)
+      super
+      freeze
+    end
+
+    def done?
+      termination == :done
+    end
+
+    def incomplete?
+      termination == :incomplete
+    end
+
+    def unexpected_eof?
+      termination == :unexpected_eof
+    end
+  end
+
+  class SSEInspector
+    MAX_EVENT_BYTES = 65_536
+    MAX_BUFFER_BYTES = 131_072
+    RESPONSE_TERMINALS = %w[response.completed response.incomplete response.failed].freeze
+
+    attr_reader :state
+
+    def initialize(max_event_bytes: MAX_EVENT_BYTES, max_buffer_bytes: MAX_BUFFER_BYTES,
+                   include_provider_message: false)
+      @max_event_bytes = bounded_limit(max_event_bytes, MAX_EVENT_BYTES, 1, 1_048_576)
+      @max_buffer_bytes = bounded_limit(max_buffer_bytes, MAX_BUFFER_BYTES, 1, 2_097_152)
+      @include_provider_message = (include_provider_message == true)
+      @buffer = +"".b
+      @at_start = true
+      @state = StreamState.new
+    end
+
+    def feed(chunk)
+      return @state unless open?
+      raise TypeError, "SSE chunks must be String instances" unless chunk.is_a?(String)
+
+      @buffer << chunk.b
+      return protocol_error! if @buffer.bytesize > @max_buffer_bytes
+
+      loop do
+        boundary = event_boundary(@buffer)
+        break unless boundary
+
+        raw, offset = boundary
+        @buffer = @buffer.byteslice(offset, @buffer.bytesize - offset) || +"".b
+        consume_event(raw)
+        break unless open?
+      end
+      @state
+    end
+
+    def close
+      return @state unless open?
+
+      consume_event(@buffer) unless @buffer.empty?
+      @buffer = +"".b
+      finish(:unexpected_eof, stream_error) if open?
+      @state
+    end
+
+    def fail
+      finish(:error, stream_error) if open?
+      @state
+    end
+
+    def self.inspect_each(enum, inspector: new)
+      return enum_for(__method__, enum, inspector: inspector) unless block_given?
+
+      begin
+        enum.each do |chunk|
+          inspector.feed(chunk)
+          yield chunk
+        end
+        inspector.close
+      rescue StandardError
+        inspector.fail
+        raise
+      end
+      inspector.state
+    end
+
+    private
+
+    def open?
+      @state.termination == :open
+    end
+
+    def bounded_limit(value, fallback, minimum, maximum)
+      return fallback unless value.is_a?(Integer)
+
+      [[value, minimum].max, maximum].min
+    end
+
+    def event_boundary(bytes)
+      indexes = []
+      index = bytes.index("\n\n".b)
+      indexes << [index, 2] if index
+      index = bytes.index("\r\r".b)
+      indexes << [index, 2] if index
+      index = bytes.index("\r\n\r\n".b)
+      indexes << [index, 4] if index
+      index = bytes.index("\n\r\n".b)
+      indexes << [index, 3] if index
+      return nil if indexes.empty?
+
+      start, length = indexes.min_by(&:first)
+      [bytes.byteslice(0, start), start + length]
+    end
+
+    def consume_event(raw)
+      return if raw.empty?
+      return protocol_error! if raw.bytesize > @max_event_bytes
+
+      text =
+        begin
+          candidate = raw.dup.force_encoding(Encoding::UTF_8)
+          raise EncodingError, "invalid UTF-8" unless candidate.valid_encoding?
+
+          candidate
+        rescue EncodingError, ArgumentError
+          return protocol_error!
+        end
+      if @at_start && text.start_with?("\uFEFF")
+        text = text.byteslice(3..)
+      end
+      @at_start = false
+
+      event_name = nil
+      data_lines = []
+      text.split(/\r\n|\n|\r/, -1).each do |line|
+        next if line.empty? || line.start_with?(":")
+
+        field, value = line.split(":", 2)
+        value = value.to_s.sub(/\A /, "")
+        case field
+        when "event"
+          event_name = value.byteslice(0, 128)
+        when "data"
+          data_lines << value
+        end
+      end
+      return if data_lines.empty?
+
+      data = data_lines.join("\n")
+      @state = with_state(events_seen: @state.events_seen + 1)
+      return finish(:done, nil) if data == "[DONE]"
+
+      payload =
+        begin
+          JSON.parse(data, allow_nan: false, max_nesting: 100)
+        rescue JSON::ParserError, ArgumentError, SystemStackError
+          return protocol_error!
+        end
+      update_protocol(payload, event_name)
+
+      if error_event?(payload, event_name)
+        return finish(:error, Normalizer.normalize(payload,
+          source: :sse, include_provider_message: @include_provider_message))
+      end
+      return finish(:done, nil) if terminal_completed?(payload, event_name)
+      return finish(:incomplete, nil) if terminal_incomplete?(payload, event_name)
+
+      @state = with_state(has_output: true) if output_event?(payload, event_name)
+      @state
+    end
+
+    def update_protocol(payload, event_name)
+      type = hash_value(payload, "type")
+      object = hash_value(payload, "object")
+      protocol =
+        if (type.is_a?(String) && type.start_with?("response.")) ||
+           (event_name.is_a?(String) && event_name.start_with?("response."))
+          :responses
+        elsif hash_value(payload, "choices").is_a?(Array) ||
+              (object.is_a?(String) && object.start_with?("chat.completion"))
+          :chat_completions
+        else
+          :unknown
+        end
+      @state = with_state(protocol: protocol) unless protocol == :unknown
+    end
+
+    def error_event?(payload, event_name)
+      return true if %w[error response.failed].include?(event_name.to_s.downcase)
+      return true if hash_value(payload, "error")
+      return true if hash_value(payload, "type").to_s == "error"
+
+      response = hash_value(payload, "response")
+      response.is_a?(Hash) &&
+        (response["status"] == "failed" || !response["error"].nil?)
+    end
+
+    def terminal_completed?(payload, event_name)
+      event_name == "response.completed" ||
+        hash_value(payload, "type") == "response.completed"
+    end
+
+    def terminal_incomplete?(payload, event_name)
+      event_name == "response.incomplete" ||
+        hash_value(payload, "type") == "response.incomplete"
+    end
+
+    def output_event?(payload, event_name)
+      signal = hash_value(payload, "type")
+      signal = event_name unless signal.is_a?(String)
+      if signal.is_a?(String) &&
+         (signal.end_with?(".delta") || signal.end_with?("-delta") ||
+          signal.start_with?("response.output_") ||
+          signal.start_with?("response.content_part.") ||
+          signal.start_with?("response.refusal.") ||
+          signal.start_with?("response.reasoning_") ||
+          signal == "response.image_generation_call.partial_image")
+        return true
+      end
+
+      choices = hash_value(payload, "choices")
+      if choices.is_a?(Array)
+        choices.first(128).each do |choice|
+          next unless choice.is_a?(Hash)
+
+          delta = choice["delta"]
+          if delta.is_a?(Hash) && %w[content refusal reasoning reasoning_content
+                                     audio tool_calls function_call].any? do |key|
+               value = delta[key]
+               !value.nil? && value != "" && value != [] && value != {}
+             end
+            return true
+          end
+          return true if choice["message"] || choice["text"]
+        end
+      end
+      delta = hash_value(payload, "delta")
+      return true if delta.is_a?(String) && !delta.empty?
+
+      response = hash_value(payload, "response")
+      return true if response.is_a?(Hash) && response["output"] && response["output"] != []
+
+      # Unknown data events are treated as potentially visible output. A false
+      # positive blocks an unsafe replay; a false negative could duplicate it.
+      !%w[response.created response.in_progress response.queued response.completed
+          response.incomplete response.failed error].include?(signal.to_s)
+    end
+
+    def hash_value(value, key)
+      value.is_a?(Hash) ? (value[key] || value[key.to_sym]) : nil
+    end
+
+    def with_state(**changes)
+      values = {
+        events_seen: @state.events_seen,
+        malformed_events: @state.malformed_events,
+        has_output: @state.has_output,
+        protocol: @state.protocol,
+        termination: @state.termination,
+        error: @state.error
+      }.merge(changes)
+      StreamState.new(**values)
+    end
+
+    def stream_error
+      ApiError.new(category: :stream, source: :sse)
+    end
+
+    def protocol_error!
+      @state = with_state(malformed_events: @state.malformed_events + 1)
+      finish(:error, stream_error)
+    end
+
+    def finish(termination, error)
+      @state = with_state(termination: termination, error: error)
+    end
+  end
+end

data/lib/openai_compatible_errors/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenAICompatibleErrors
+  VERSION = "0.1.0"
+end

data/lib/openai_compatible_errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "openai_compatible_errors/version"
+require_relative "openai_compatible_errors/error"
+require_relative "openai_compatible_errors/headers"
+require_relative "openai_compatible_errors/redaction"
+require_relative "openai_compatible_errors/normalize"
+require_relative "openai_compatible_errors/retry"
+require_relative "openai_compatible_errors/sse"
+
+module OpenAICompatibleErrors
+  module_function
+
+  def redact_sensitive_text(value, **options)
+    Redaction.redact_sensitive_text(value, **options)
+  end
+
+  def sanitize_for_log(value, **options)
+    Redaction.sanitize_for_log(value, **options)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "openai_compatible_errors"
+
+class Minitest::Test
+  def assert_includes_no_secret(value, secret)
+    refute_includes(value.to_s, secret)
+  end
+end

data/test/test_normalize.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "timeout"
+
+class NormalizeTest < Minitest::Test
+  FakeResponse = Struct.new(:status, :headers, :body, keyword_init: true)
+
+  def test_normalizes_http_rate_limit_without_retaining_provider_message
+    error = OpenAICompatibleErrors.normalize_error(
+      status: 429,
+      headers: { "Retry-After" => "2", "X-Request-Id" => "req_01" },
+      body: {
+        error: {
+          code: "rate_limit_exceeded",
+          type: "requests",
+          message: "Bearer very-secret-token"
+        }
+      }
+    )
+
+    assert_equal :rate_limit, error.category
+    assert_equal :http, error.source
+    assert_equal 429, error.status
+    assert_equal "rate_limit_exceeded", error.code
+    assert_equal "requests", error.type
+    assert_equal "req_01", error.request_id
+    assert_equal 2_000, error.retry_after_ms
+    assert_nil error.provider_message
+    assert_equal "The API rate limit was reached.", error.message
+    assert_includes_no_secret(error.to_h, "very-secret-token")
+  end
+
+  def test_provider_message_requires_explicit_opt_in_and_is_redacted
+    error = OpenAICompatibleErrors.normalize_error(
+      {
+        status: 401,
+        body: {
+          error: { message: "authorization=never-log-this Bearer also-never-log" }
+        }
+      },
+      include_provider_message: true
+    )
+
+    assert_equal :authentication, error.category
+    assert_includes error.provider_message, "[REDACTED]"
+    assert_includes_no_secret(error.provider_message, "never-log-this")
+    assert_includes_no_secret(error.provider_message, "also-never-log")
+    assert_nil error.to_h[:provider_message]
+    assert_includes error.to_h(include_provider_message: true), :provider_message
+  end
+
+  def test_response_shape_and_http_date_retry_after_are_supported
+    now = Time.utc(2026, 8, 9, 0, 0, 0)
+    response = FakeResponse.new(
+      status: "503",
+      headers: { "retry-after" => (now + 5).httpdate, "x-request-id" => "req_503" },
+      body: '{"error":{"code":"server_error","type":"internal"}}'
+    )
+
+    error = OpenAICompatibleErrors.normalize_error(response, now: now)
+
+    assert_equal :upstream, error.category
+    assert_equal :http, error.source
+    assert_equal 5_000, error.retry_after_ms
+    assert_equal "req_503", error.request_id
+    assert_equal "server_error", error.code
+    assert_equal "internal", error.type
+  end
+
+  def test_status_and_structured_code_precede_exception_text
+    error = OpenAICompatibleErrors.normalize_error(
+      Timeout::Error.new("connection reset"),
+      status: 400,
+      body: { error: { code: "invalid_request_error" } }
+    )
+
+    assert_equal :validation, error.category
+  end
+
+  def test_timeout_exception_is_classified_without_logging_message
+    error = OpenAICompatibleErrors.normalize_error(Timeout::Error.new("secret prompt"))
+
+    assert_equal :timeout, error.category
+    assert_nil error.provider_message
+    assert_includes_no_secret(error.to_h, "secret prompt")
+  end
+
+  def test_malformed_retry_hint_saturates_to_conservative_sentinel
+    error = OpenAICompatibleErrors.normalize_error(
+      status: 429,
+      headers: { "retry-after" => "soon" }
+    )
+
+    assert_equal OpenAICompatibleErrors::Headers::MAX_RETRY_AFTER_MS, error.retry_after_ms
+  end
+
+  def test_invalid_identifiers_and_unbounded_body_are_dropped
+    error = OpenAICompatibleErrors.normalize_error(
+      status: 500,
+      headers: { "x-request-id" => "Bearer should-not-pass" },
+      body: "{\"error\":{\"code\":\"x\"}}" + (" " * 70_000)
+    )
+
+    assert_equal :server, error.category
+    assert_nil error.request_id
+    assert_nil error.code
+  end
+
+  def test_api_error_is_immutable_and_hides_provider_message_from_inspect
+    error = OpenAICompatibleErrors::ApiError.new(
+      category: :network,
+      source: :unknown,
+      provider_message: "do-not-print"
+    )
+
+    assert_predicate error, :frozen?
+    refute_includes error.inspect, "do-not-print"
+  end
+end

data/test/test_redaction.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class RedactionTest < Minitest::Test
+  def test_redacts_common_credentials
+    result = OpenAICompatibleErrors.redact_sensitive_text(
+      "Bearer abcdefghijklmnop sk-secret-token-123 api_key=also-secret"
+    )
+
+    assert_includes result, "[REDACTED]"
+    assert_includes_no_secret(result, "abcdefghijklmnop")
+    assert_includes_no_secret(result, "secret-token-123")
+    assert_includes_no_secret(result, "also-secret")
+  end
+
+  def test_sanitizer_redacts_sensitive_keys_without_reading_exception_message
+    error = RuntimeError.new("customer prompt should never become diagnostic context")
+    value = {
+      "api_key" => "key-to-hide",
+      "nested" => { "authorization" => "Bearer key-to-hide", "ok" => "fine" },
+      "exception" => error
+    }
+
+    sanitized = OpenAICompatibleErrors.sanitize_for_log(value)
+
+    assert_equal "[REDACTED]", sanitized["api_key"]
+    assert_equal "[REDACTED]", sanitized["nested"]["authorization"]
+    assert_equal "fine", sanitized["nested"]["ok"]
+    assert_equal "[RuntimeError]", sanitized["exception"]
+    assert_includes_no_secret(sanitized, "customer prompt")
+    assert_includes_no_secret(sanitized, "key-to-hide")
+  end
+
+  def test_sanitizer_breaks_cycles_and_bounds_collections
+    looped = []
+    looped << looped
+    sanitized = OpenAICompatibleErrors.sanitize_for_log(
+      { "items" => (1..40).to_a, "loop" => looped },
+      limits: OpenAICompatibleErrors::Redaction::Limits.new(max_items: 3, max_keys: 3)
+    )
+
+    assert_equal [1, 2, 3, "[TRUNCATED]"], sanitized["items"]
+    assert_equal ["[REDACTED]"], sanitized["loop"]
+  end
+end

data/test/test_retry.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class RetryTest < Minitest::Test
+  def error(category: :rate_limit, retry_after_ms: nil)
+    OpenAICompatibleErrors::ApiError.new(
+      category: category,
+      source: :http,
+      retry_after_ms: retry_after_ms
+    )
+  end
+
+  def context(**overrides)
+    OpenAICompatibleErrors::RetryContext.new(
+      method: "POST",
+      phase: :http_error,
+      replay_safety: :safe,
+      attempt: 1,
+      elapsed_ms: 100,
+      **overrides
+    )
+  end
+
+  def test_uses_server_retry_after_when_evidence_is_safe
+    plan = OpenAICompatibleErrors.decide_retry(error(retry_after_ms: 2_000), context)
+
+    assert_equal :retry, plan.action
+    assert_equal :transient_and_replay_safe, plan.reason
+    assert_equal 2_000, plan.delay_ms
+    assert_equal :server, plan.delay_source
+  end
+
+  def test_never_retries_after_partial_stream_output
+    plan = OpenAICompatibleErrors.decide_retry(error, context(has_stream_output: true))
+
+    assert_equal :do_not_retry, plan.action
+    assert_equal :partial_stream_output, plan.reason
+  end
+
+  def test_treats_quota_as_permanent
+    plan = OpenAICompatibleErrors.decide_retry(error(category: :quota), context)
+
+    assert_equal :do_not_retry, plan.action
+    assert_equal :permanent_error, plan.reason
+  end
+
+  def test_requires_known_phase_and_replay_safety
+    phase_plan = OpenAICompatibleErrors.decide_retry(error, context(phase: :unknown))
+    safety_plan = OpenAICompatibleErrors.decide_retry(
+      error,
+      context(replay_safety: :unknown)
+    )
+
+    assert_equal :manual_decision, phase_plan.action
+    assert_equal :unknown_phase, phase_plan.reason
+    assert_equal :manual_decision, safety_plan.action
+    assert_equal :unknown_replay_safety, safety_plan.reason
+  end
+
+  def test_honors_attempt_and_time_budgets
+    attempt_plan = OpenAICompatibleErrors.decide_retry(
+      error,
+      context(attempt: 3),
+      policy: OpenAICompatibleErrors::RetryPolicy.new(max_attempts: 3)
+    )
+    time_plan = OpenAICompatibleErrors.decide_retry(
+      error,
+      context(elapsed_ms: 30_000)
+    )
+
+    assert_equal :attempt_budget_exhausted, attempt_plan.reason
+    assert_equal :time_budget_exhausted, time_plan.reason
+  end
+
+  def test_invalid_random_source_fails_closed
+    plan = OpenAICompatibleErrors.decide_retry(error, context, random: -> { 2 })
+
+    assert_equal :manual_decision, plan.action
+    assert_equal :invalid_context, plan.reason
+  end
+
+  def test_malformed_header_sentinel_does_not_fit_default_delay_budget
+    plan = OpenAICompatibleErrors.decide_retry(
+      error(retry_after_ms: OpenAICompatibleErrors::Headers::MAX_RETRY_AFTER_MS),
+      context
+    )
+
+    assert_equal :do_not_retry, plan.action
+    assert_equal :retry_after_exceeds_budget, plan.reason
+  end
+end

data/test/test_sse.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class SSETest < Minitest::Test
+  def test_inspects_chat_chunks_across_byte_boundaries
+    inspector = OpenAICompatibleErrors::SSEInspector.new
+    event = "data: {\"choices\":[{\"delta\":{\"content\":\"hi\"}}]}\n\n"
+    event.bytes.each_slice(3) { |bytes| inspector.feed(bytes.pack("C*")) }
+    inspector.feed("data: [DONE]\n\n")
+
+    assert_equal :chat_completions, inspector.state.protocol
+    assert inspector.state.has_output
+    assert inspector.state.done?
+    assert_equal 2, inspector.state.events_seen
+  end
+
+  def test_responses_metadata_does_not_claim_output_but_delta_does
+    inspector = OpenAICompatibleErrors::SSEInspector.new
+    inspector.feed("event: response.created\ndata: {\"type\":\"response.created\"}\n\n")
+    refute inspector.state.has_output
+
+    inspector.feed(
+      "event: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"delta\":\"hello\"}\n\n"
+    )
+    inspector.feed("event: response.completed\ndata: {\"type\":\"response.completed\"}\n\n")
+
+    assert_equal :responses, inspector.state.protocol
+    assert inspector.state.has_output
+    assert inspector.state.done?
+  end
+
+  def test_error_event_normalizes_without_provider_message_by_default
+    inspector = OpenAICompatibleErrors::SSEInspector.new
+    inspector.feed(
+      "event: error\ndata: {\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Bearer never-log\"}}\n\n"
+    )
+
+    assert_equal :error, inspector.state.termination
+    assert_equal :sse, inspector.state.error.source
+    assert_equal :rate_limit, inspector.state.error.category
+    assert_nil inspector.state.error.provider_message
+    assert_includes_no_secret(inspector.state.error.to_h, "never-log")
+  end
+
+  def test_malformed_utf8_and_oversized_events_become_stream_errors
+    malformed = OpenAICompatibleErrors::SSEInspector.new
+    malformed.feed("data: ".b + [0xFF].pack("C") + "\n\n".b)
+    assert_equal :error, malformed.state.termination
+    assert_equal 1, malformed.state.malformed_events
+
+    oversized = OpenAICompatibleErrors::SSEInspector.new(max_event_bytes: 10)
+    oversized.feed("data: {\"x\":\"too long\"}\n\n")
+    assert_equal :error, oversized.state.termination
+    assert_equal 1, oversized.state.malformed_events
+  end
+
+  def test_close_records_unexpected_eof_after_output
+    inspector = OpenAICompatibleErrors::SSEInspector.new
+    inspector.feed("data: {\"choices\":[{\"delta\":{\"content\":\"partial\"}}]}\n\n")
+    inspector.close
+
+    assert inspector.state.has_output
+    assert inspector.state.unexpected_eof?
+    assert_equal :stream, inspector.state.error.category
+  end
+
+  def test_adapter_preserves_chunks_and_marks_source_failure
+    inspector = OpenAICompatibleErrors::SSEInspector.new
+    chunks = ["data: {\"choices\":[{\"delta\":{\"content\":\"ok\"}}]}\n\n", "data: [DONE]\n\n"]
+    received = []
+
+    state = OpenAICompatibleErrors::SSEInspector.inspect_each(chunks, inspector: inspector) do |chunk|
+      received << chunk
+    end
+
+    assert_equal chunks, received
+    assert state.done?
+  end
+end