openai-compatible-errors 0.1.0

data/lib/openai_compatible_errors/normalize.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenAICompatibleErrors
+  module Normalizer
+    MAX_BODY_BYTES = 65_536
+    MAX_IDENTIFIER_BYTES = 256
+    UNSET = Object.new.freeze
+
+    module_function
+
+    def normalize(input, status: nil, headers: nil, body: nil,
+                  include_provider_message: false, now: Time.now, source: nil)
+      response_status, response_headers, response_body = response_parts(input)
+      status = valid_status(status) || response_status
+      headers = response_headers if headers.nil?
+      body = response_body if body.nil?
+
+      decoded = decode_body(body.nil? && input.is_a?(Hash) ? input : body)
+      payload = error_payload(decoded)
+      code = safe_identifier(first_value(:code, payload, decoded, input))
+      error_type = safe_identifier(first_value(:type, payload, decoded, input))
+      request_id = Headers.request_id(headers) ||
+                   safe_identifier(first_value(:request_id, payload, decoded, input))
+      class_name = safe_class_name(input)
+      exception_message = exception_message(input)
+      category = classify(status: status, code: code, error_type: error_type,
+                          class_name: class_name, exception_message: exception_message)
+      provider_message =
+        if include_provider_message
+          Redaction.redact_sensitive_text(
+            first_text(payload, decoded, input),
+            max_chars: 2_000
+          )
+        end
+
+      ApiError.new(
+        category: category,
+        source: source || detect_source(input, status),
+        status: status,
+        code: code,
+        type: error_type,
+        request_id: request_id,
+        retry_after_ms: Headers.retry_after_ms(headers, now: now),
+        provider_message: provider_message
+      )
+    end
+
+    def response_parts(input)
+      status = valid_status(read(input, :status_code)) || valid_status(read(input, :status))
+      headers = read(input, :headers)
+      content = first_present(read(input, :body), read(input, :content), read(input, :data))
+
+      nested_response = read(input, :response)
+      if nested_response && nested_response != input
+        status ||= valid_status(read(nested_response, :status_code)) ||
+                   valid_status(read(nested_response, :status))
+        headers ||= read(nested_response, :headers)
+        content = first_present(content, read(nested_response, :body),
+                                 read(nested_response, :content),
+                                 read(nested_response, :data))
+      end
+
+      [status, headers, content]
+    end
+
+    def read(value, *keys)
+      return UNSET if value.nil?
+
+      if value.is_a?(Hash)
+        keys.each do |key|
+          return value[key] if value.key?(key)
+          string_key = key.to_s
+          return value[string_key] if value.key?(string_key)
+        end
+        return UNSET
+      end
+
+      keys.each do |key|
+        next unless value.respond_to?(key)
+
+        begin
+          result = value.public_send(key)
+          return result unless result.nil?
+        rescue StandardError
+          next
+        end
+      end
+      UNSET
+    end
+
+    def first_present(*values)
+      values.find { |value| value != UNSET && !value.nil? }
+    end
+
+    def valid_status(value)
+      candidate =
+        if value.is_a?(Integer) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
+          value
+        elsif value.is_a?(String) && value.bytesize <= 16 && value.strip.match?(/\A\d+\z/)
+          value.to_i
+        end
+      candidate && candidate.between?(100, 599) ? candidate : nil
+    end
+
+    def decode_body(value)
+      return nil if value == UNSET || value.nil?
+      return value if value.is_a?(Hash) || value.is_a?(Array)
+
+      if value.is_a?(String)
+        return nil if value.bytesize > MAX_BODY_BYTES
+
+        text = value.scrub
+        candidate = text.strip
+        return value unless candidate.start_with?("{", "[")
+
+        begin
+          return JSON.parse(candidate, allow_nan: false, max_nesting: 100)
+        rescue JSON::ParserError, ArgumentError, SystemStackError
+          return value
+        end
+      end
+
+      if value.respond_to?(:to_hash)
+        begin
+          converted = value.to_hash
+          return converted if converted.is_a?(Hash)
+        rescue StandardError
+          return value
+        end
+      end
+      value
+    end
+
+    def error_payload(value)
+      return value unless value.is_a?(Hash)
+
+      nested = value[:response] || value["response"]
+      if nested.is_a?(Hash)
+        nested_error = nested[:error] || nested["error"]
+        return nested_error unless nested_error.nil?
+      end
+      error = value[:error] || value["error"]
+      error.nil? ? value : error
+    end
+
+    def first_value(field, *values)
+      values.each do |value|
+        next unless value.is_a?(Hash)
+
+        return value[field] if value.key?(field) && !value[field].nil?
+        string_key = field.to_s
+        return value[string_key] if value.key?(string_key) && !value[string_key].nil?
+      end
+      UNSET
+    end
+
+    def first_text(*values)
+      values.each do |value|
+        next unless value.is_a?(Hash)
+
+        candidate = value[:message] || value["message"]
+        return candidate if candidate.is_a?(String) && !candidate.empty?
+      end
+      values.each do |value|
+        candidate = exception_message(value)
+        return candidate unless candidate.nil?
+      end
+      nil
+    end
+
+    def safe_identifier(value)
+      return nil unless value.is_a?(String)
+
+      candidate = value.strip
+      return nil if candidate.empty? || candidate.bytesize > MAX_IDENTIFIER_BYTES
+      return nil unless candidate.match?(/\A[A-Za-z0-9][A-Za-z0-9._:\/-]*\z/)
+      return nil if candidate.match?(/bearer|api[_ -]?key|secret|token/i)
+
+      candidate
+    end
+
+    def exception_message(value)
+      return nil unless value.is_a?(Exception)
+
+      begin
+        text = value.message
+        text.is_a?(String) && text.bytesize <= 2_000 ? text : nil
+      rescue StandardError
+        nil
+      end
+    end
+
+    def safe_class_name(value)
+      name = value.class.name
+      name.is_a?(String) ? name.byteslice(0, 256).to_s : ""
+    rescue StandardError
+      ""
+    end
+
+    def detect_source(input, status)
+      name = safe_class_name(input)
+      return :openai_sdk if name.match?(/OpenAI|APIError|RateLimitError|AuthenticationError/i)
+      return :httpx if name.start_with?("HTTPX::")
+      return :http if status
+
+      :unknown
+    end
+
+    def classify(status:, code:, error_type:, class_name:, exception_message:)
+      structured = [code, error_type, class_name].compact.join(" ").downcase
+      transport = [structured, exception_message].compact.join(" ").downcase
+
+      return :schema if structured.include?("apiresponsevalidationerror")
+      return :validation if [400, 422].include?(status)
+      return :conflict if status == 409
+      return :authentication if status == 401
+      return :permission if status == 403
+      if status == 404
+        return structured.match?(/model|deployment|resource/) ? :not_found : :endpoint
+      end
+      return :timeout if status == 408
+      return :payload_too_large if status == 413
+      if status == 429
+        return structured.match?(/insufficient[_ -]?quota|quota[_ -]?(exhausted|exceeded)|billing|credit/) ? :quota : :rate_limit
+      end
+      return :upstream if [502, 503, 504].include?(status)
+      return :server if status && status >= 500
+      return :validation if status && status >= 400
+
+      return :timeout if structured.match?(/timeout|timedout|etimedout/)
+      return :network if structured.match?(/connection|connecterror|proxyerror|protocolerror/)
+      return :aborted if transport.match?(/abort|cancel/)
+      return :quota if structured.match?(/insufficient[_ -]?quota|quota[_ -]?(exhausted|exceeded)|billing|credit/)
+      return :authentication if structured.match?(/invalid[_ -]?api[_ -]?key|authentication|unauthori[sz]ed/)
+      return :permission if structured.match?(/permission|forbidden|access[_ -]?denied/)
+      return :rate_limit if structured.match?(/rate[_ -]?limit/)
+      return :timeout if transport.match?(/timed?[_ -]?out|timeout|etimedout/)
+      return :network if transport.match?(/connection|econnreset|econnrefused|enotfound|network/)
+      return :schema if structured.match?(/json|schema|parse[_ -]?error|malformed|decode/)
+
+      :unknown
+    end
+  end
+
+  module_function
+
+  def normalize_error(input = nil, **options)
+    Normalizer.normalize(input, **options)
+  end
+
+  alias normalize normalize_error
+end

data/lib/openai_compatible_errors/redaction.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module OpenAICompatibleErrors
+  module Redaction
+    SENSITIVE_KEY = /(authorization|api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|secret|password|cookie|prompt|completion)/i
+    REDACTED = "[REDACTED]".freeze
+    TRUNCATED = "[TRUNCATED]".freeze
+
+    Limits = Struct.new(:max_depth, :max_nodes, :max_keys, :max_items,
+                        :max_chars, :max_replacements, keyword_init: true) do
+      def initialize(max_depth: 4, max_nodes: 250, max_keys: 32, max_items: 32,
+                     max_chars: 8_192, max_replacements: 64)
+        super
+        raise ArgumentError, "limits must be positive" unless [max_depth, max_nodes,
+          max_keys, max_items, max_chars, max_replacements].all? do |value|
+          value.is_a?(Integer) && value.positive?
+        end
+        freeze
+      end
+    end
+
+    module_function
+
+    def redact_sensitive_text(value, max_chars: 2_000)
+      return nil unless value.is_a?(String)
+
+      text = value.encode("UTF-8", invalid: :replace, undef: :replace, replace: "�")
+      replacements = 0
+      patterns = [
+        [/\bBearer\s+[A-Za-z0-9._~+\/=-]+/i, "Bearer #{REDACTED}"],
+        [/\b(?:sk(?:-proj|-ant)?|xai|ghp|github_pat|hf|r8)[_-][A-Za-z0-9_-]{8,}/, REDACTED],
+        [/(api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|authorization)\s*[:=]\s*[^\s,;]+/i,
+         "\\1=#{REDACTED}"]
+      ]
+      patterns.each do |pattern, replacement|
+        text = text.gsub(pattern) do
+          replacements += 1
+          if replacement.include?("\\1")
+            "#{Regexp.last_match(1)}=#{REDACTED}"
+          else
+            replacement
+          end
+        end
+      end
+      text = text.byteslice(0, max_chars).to_s.scrub
+      replacements.positive? ? text : text
+    rescue EncodingError
+      REDACTED
+    end
+
+    def sanitize_for_log(value, limits: Limits.new)
+      state = { nodes: 0, chars: 0, replacements: 0, seen: {} }
+      sanitize_value(value, depth: 0, limits: limits, state: state)
+    end
+
+    def sensitive_key?(key)
+      key.is_a?(String) || key.is_a?(Symbol) ? key.to_s.match?(SENSITIVE_KEY) : false
+    end
+
+    def sanitize_value(value, depth:, limits:, state:)
+      state[:nodes] += 1
+      return REDACTED if state[:nodes] > limits.max_nodes
+      return REDACTED if depth > limits.max_depth
+
+      case value
+      when nil, true, false, Numeric
+        value
+      when Symbol
+        value.to_s
+      when String
+        sanitize_string(value, limits, state)
+      when Exception
+        "[#{value.class.name || "Exception"}]"
+      when Hash
+        return REDACTED if state[:seen][value.object_id]
+
+        state[:seen][value.object_id] = true
+        result = {}
+        value.first(limits.max_keys).each do |key, item|
+          normalized_key = key.is_a?(String) || key.is_a?(Symbol) ? key.to_s : "[KEY]"
+          result[normalized_key] = if sensitive_key?(normalized_key)
+                                     state[:replacements] += 1
+                                     REDACTED
+                                   else
+                                     sanitize_value(item, depth: depth + 1,
+                                                    limits: limits, state: state)
+                                   end
+        end
+        result["[TRUNCATED]"] = TRUNCATED if value.size > limits.max_keys
+        result
+      when Array
+        return REDACTED if state[:seen][value.object_id]
+
+        state[:seen][value.object_id] = true
+        result = value.first(limits.max_items).map do |item|
+          sanitize_value(item, depth: depth + 1, limits: limits, state: state)
+        end
+        result << TRUNCATED if value.size > limits.max_items
+        result
+      else
+        "[#{value.class.name || "Object"}]"
+      end
+    end
+
+    def sanitize_string(value, limits, state)
+      text = redact_sensitive_text(value, max_chars: limits.max_chars)
+      state[:chars] += text.to_s.length
+      if state[:chars] > limits.max_chars
+        state[:replacements] += 1
+        return REDACTED
+      end
+      text
+    end
+  end
+end

data/lib/openai_compatible_errors/retry.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module OpenAICompatibleErrors
+  RETRY_ACTIONS = %i[retry do_not_retry manual_decision].freeze
+  RETRY_REASONS = %i[
+    transient_and_replay_safe
+    partial_stream_output
+    request_completed
+    conflict_requires_resolution
+    replay_unsafe
+    caller_aborted
+    permanent_error
+    attempt_budget_exhausted
+    time_budget_exhausted
+    retry_after_exceeds_budget
+    unclassified_error
+    unknown_phase
+    unknown_replay_safety
+    invalid_context
+  ].freeze
+  REQUEST_PHASES = %i[
+    before_send awaiting_headers http_error sse_before_output
+    sse_after_output completed unknown
+  ].freeze
+  REPLAY_SAFETY = %i[safe unsafe unknown].freeze
+  DELAY_SOURCES = %i[server backoff].freeze
+
+  class RetryContext
+    attr_reader :method, :phase, :replay_safety, :attempt, :elapsed_ms,
+                :has_stream_output
+
+    def initialize(method:, phase:, replay_safety:, attempt:, elapsed_ms:,
+                   has_stream_output: false)
+      @method = method.is_a?(String) ? method.strip.upcase : ""
+      @phase = coerce(phase, REQUEST_PHASES, :unknown)
+      @replay_safety = coerce(replay_safety, REPLAY_SAFETY, :unknown)
+      @attempt = attempt.is_a?(Integer) && attempt.positive? ? attempt : 0
+      @elapsed_ms = elapsed_ms.is_a?(Integer) && elapsed_ms >= 0 ? elapsed_ms : -1
+      @has_stream_output = (has_stream_output == true)
+      freeze
+    end
+
+    private
+
+    def coerce(value, allowed, fallback)
+      candidate = value.is_a?(Symbol) ? value : value.to_s.strip.downcase.to_sym
+      allowed.include?(candidate) ? candidate : fallback
+    end
+  end
+
+  class RetryPolicy
+    attr_reader :max_attempts, :max_elapsed_ms, :base_delay_ms,
+                :max_delay_ms, :jitter
+
+    def initialize(max_attempts: 3, max_elapsed_ms: 30_000, base_delay_ms: 500,
+                   max_delay_ms: 10_000, jitter: :full)
+      @max_attempts = positive_integer(max_attempts)
+      @max_elapsed_ms = positive_integer(max_elapsed_ms)
+      @base_delay_ms = non_negative_integer(base_delay_ms)
+      @max_delay_ms = positive_integer(max_delay_ms)
+      jitter_symbol = jitter.is_a?(Symbol) || jitter.is_a?(String) ? jitter.to_sym : :full
+      @jitter = %i[full none].include?(jitter_symbol) ? jitter_symbol : :full
+      raise ArgumentError, "max_delay_ms must be at least base_delay_ms" if @max_delay_ms < @base_delay_ms
+
+      freeze
+    end
+
+    private
+
+    def positive_integer(value)
+      raise ArgumentError, "expected a positive integer" unless value.is_a?(Integer) && value.positive?
+
+      value
+    end
+
+    def non_negative_integer(value)
+      raise ArgumentError, "expected a non-negative integer" unless value.is_a?(Integer) && value >= 0
+
+      value
+    end
+  end
+
+  class RetryPlan
+    attr_reader :action, :reason, :delay_ms, :delay_source
+
+    def initialize(action:, reason:, delay_ms: nil, delay_source: nil)
+      action_symbol = action.is_a?(Symbol) || action.is_a?(String) ? action.to_sym : nil
+      reason_symbol = reason.is_a?(Symbol) || reason.is_a?(String) ? reason.to_sym : nil
+      @action = RETRY_ACTIONS.include?(action_symbol) ? action_symbol : :manual_decision
+      @reason = RETRY_REASONS.include?(reason_symbol) ? reason_symbol : :invalid_context
+      @delay_ms = delay_ms.is_a?(Integer) && delay_ms >= 0 ? delay_ms : nil
+      source_symbol = delay_source.is_a?(Symbol) || delay_source.is_a?(String) ? delay_source.to_sym : nil
+      @delay_source = DELAY_SOURCES.include?(source_symbol) ? source_symbol : nil
+      freeze
+    end
+
+    def retry?
+      @action == :retry
+    end
+
+    def do_not_retry?
+      @action == :do_not_retry
+    end
+
+    def manual_decision?
+      @action == :manual_decision
+    end
+
+    def to_h
+      { action: @action, reason: @reason, delay_ms: @delay_ms,
+        delay_source: @delay_source }.compact.freeze
+    end
+  end
+
+  module Retry
+    TRANSIENT = %i[rate_limit timeout network upstream server stream].freeze
+    PERMANENT = %i[authentication permission quota validation not_found
+                   payload_too_large endpoint].freeze
+
+    module_function
+
+    def decide_retry(error, context, policy: RetryPolicy.new, random: nil)
+      return plan(:manual_decision, :invalid_context) unless error.is_a?(ApiError)
+      return plan(:manual_decision, :invalid_context) unless context.is_a?(RetryContext)
+      return plan(:manual_decision, :invalid_context) unless policy.is_a?(RetryPolicy)
+      return plan(:manual_decision, :invalid_context) unless context.attempt.positive? &&
+        context.elapsed_ms >= 0 && !context.method.empty?
+
+      return plan(:do_not_retry, :partial_stream_output) if context.has_stream_output ||
+        context.phase == :sse_after_output
+      return plan(:do_not_retry, :request_completed) if context.phase == :completed
+      return plan(:do_not_retry, :caller_aborted) if error.category == :aborted
+      return plan(:manual_decision, :conflict_requires_resolution) if error.category == :conflict
+      return plan(:do_not_retry, :permanent_error) if PERMANENT.include?(error.category)
+      return plan(:do_not_retry, :replay_unsafe) if context.replay_safety == :unsafe
+      return plan(:manual_decision, :unknown_phase) if context.phase == :unknown
+      return plan(:manual_decision, :unknown_replay_safety) if context.replay_safety == :unknown
+      return plan(:manual_decision, :unclassified_error) unless TRANSIENT.include?(error.category)
+      return plan(:do_not_retry, :attempt_budget_exhausted) if context.attempt >= policy.max_attempts
+      return plan(:do_not_retry, :time_budget_exhausted) if context.elapsed_ms >= policy.max_elapsed_ms
+
+      if error.retry_after_ms
+        delay = error.retry_after_ms
+        return plan(:do_not_retry, :retry_after_exceeds_budget) if delay > policy.max_delay_ms ||
+          context.elapsed_ms + delay > policy.max_elapsed_ms
+
+        return RetryPlan.new(action: :retry, reason: :transient_and_replay_safe,
+                             delay_ms: delay, delay_source: :server)
+      end
+
+      exponent = [context.attempt - 1, 30].min
+      cap = [policy.base_delay_ms * (2**exponent), policy.max_delay_ms].min
+      delay =
+        if policy.jitter == :none
+          cap
+        else
+          sample = random ? random.call : Kernel.rand
+          return plan(:manual_decision, :invalid_context) unless sample.is_a?(Numeric) &&
+            sample.finite? && sample >= 0 && sample <= 1
+
+          (cap * sample).round
+        end
+      return plan(:do_not_retry, :time_budget_exhausted) if context.elapsed_ms + delay > policy.max_elapsed_ms
+
+      RetryPlan.new(action: :retry, reason: :transient_and_replay_safe,
+                    delay_ms: delay, delay_source: :backoff)
+    rescue StandardError
+      plan(:manual_decision, :invalid_context)
+    end
+
+    def plan(action, reason)
+      RetryPlan.new(action: action, reason: reason)
+    end
+    private_class_method :plan
+  end
+
+  module_function
+
+  def decide_retry(error, context, **options)
+    Retry.decide_retry(error, context, **options)
+  end
+end