openai-compatible-errors 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9efa61faaf3046bde793f560e4c317206e66bdc514f04198321791a5fb0a292
+  data.tar.gz: bc57fd669d5248a34328d45aebea298ce52fc8d0164ce663bc0f8b9a83d9fd58
+SHA512:
+  metadata.gz: eef6cd4bcb3a1a34471396797d1f3d02248cbbfca85f252c0319399d8f1c58eae43c004d9fafc70cdd3e1824fbbf567b1e1b48e26329160903318cbf15c3bf27
+  data.tar.gz: b0fbee45f6add7e573f598c0e18a8fba8c2ac02d497c39d49a2f1ce0095690b4d07d5dc28da7a819f918e5087ba1e3bc0bddd181a3c7796fc01a2c6fd9a97fa4

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this gem are documented here.
+
+## [0.1.0] - 2026-08-09
+
+Initial public release.
+
+- Normalize HTTP-like hashes, response objects and common SDK exception shapes.
+- Classify authentication, permission, rate-limit, quota, validation, conflict,
+  transport, upstream, server, schema and stream failures.
+- Parse bounded Retry-After and millisecond retry hints.
+- Return immutable, safe-by-default error snapshots with optional redacted
+  provider text.
+- Plan retries only when the caller supplies replay-safety and stream-phase
+  evidence.
+- Inspect Chat Completions and Responses Server-Sent Events incrementally
+  without retaining generated output.
+- Provide bounded recursive log sanitization with cycle detection.
+
+[0.1.0]: https://github.com/airouter-dev/openai-compatible-errors-ruby/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+## Local validation
+
+This gem intentionally has no runtime dependencies. With Ruby 3.0 or newer:
+
+    bundle install
+    bundle exec rake test
+    gem build openai-compatible-errors.gemspec
+
+The tests never call an API, open a network connection, sleep, or use real
+credentials. Keep fixtures synthetic and bounded.
+
+## Design boundaries
+
+- normalize_error returns a snapshot; it does not raise a provider exception
+  again or retain a raw body.
+- decide_retry returns a plan; the caller owns waiting, cancellation,
+  idempotency and replay.
+- SSEInspector retains replay-boundary state only, never generated text.
+- Redaction reduces logging risk but is not a substitute for a data-retention
+  policy.
+
+Please add a regression test for every new provider shape and document whether
+the shape is observed in HTTP headers, a structured body, an SDK exception, or
+an SSE event.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI ROUTER contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,213 @@
+# openai-compatible-errors
+
+openai-compatible-errors is a zero-runtime-dependency Ruby library for the
+failure boundary around OpenAI-compatible HTTP APIs. It turns provider-specific
+HTTP, Ruby SDK and JSON error shapes into a small immutable snapshot; parses
+Retry-After; makes replay safety explicit before a retry; redacts bounded
+diagnostics; and incrementally inspects Chat Completions or Responses
+Server-Sent Events (SSE).
+
+It does not send requests, sleep, retry automatically, buffer an entire stream,
+or retain a raw provider response. The caller remains responsible for
+idempotency, cancellation, budget accounting and request replay.
+
+## Install
+
+    gem "openai-compatible-errors"
+
+Then:
+
+    bundle install
+
+Ruby 3.0 or newer is supported. The gem has no runtime dependencies, so it can
+sit at the boundary of a Net::HTTP, Faraday, HTTPX or OpenAI-style client
+without forcing a transport choice.
+
+## Normalize a failure safely
+
+The normalizer accepts a response-like hash, a response object exposing
+status/status_code, headers and body, or an exception carrying a nested
+response. Provider-controlled text is not copied into the result by default.
+
+    require "openai_compatible_errors"
+
+    error = OpenAICompatibleErrors.normalize_error(
+      status: 429,
+      headers: {
+        "retry-after" => "2",
+        "x-request-id" => "req_demo_01"
+      },
+      body: {
+        "error" => {
+          "type" => "requests",
+          "code" => "rate_limit_exceeded",
+          "message" => "provider detail"
+        }
+      }
+    )
+
+    error.category         #=> :rate_limit
+    error.status           #=> 429
+    error.retry_after_ms   #=> 2000
+    error.request_id       #=> "req_demo_01"
+    error.provider_message #=> nil
+
+    logger.warn(error.to_log_h)
+
+The returned ApiError has stable library-owned message text and only validated
+identifiers. It never has a body, headers, exception cause, traceback, prompt
+or generated-output field. If an operator genuinely needs provider text, opt in
+explicitly; common bearer and API-key formats are still redacted and the value
+is bounded:
+
+    diagnostic = OpenAICompatibleErrors.normalize_error(
+      exception,
+      include_provider_message: true
+    )
+    logger.warn(diagnostic.to_log_h(include_provider_message: true))
+
+The opt-in is a risk reduction, not a guarantee that arbitrary provider text is
+appropriate for a production log.
+
+### HTTP and SDK adapters without dependencies
+
+No client gem is required at runtime. A Net::HTTP response works directly:
+
+    response = Net::HTTP::Post.new("/v1/responses")
+    # ... perform the request ...
+    error = OpenAICompatibleErrors.normalize_error(response)
+
+For a client whose response object uses different names, pass the boundary
+explicitly:
+
+    error = OpenAICompatibleErrors.normalize_error(
+      exception,
+      status: response.status.to_i,
+      headers: response.each_header.to_h,
+      body: response.body
+    )
+
+Classification prefers HTTP status, structured error.code/error.type and
+exception class names. Free-form exception messages are not retained and are
+only a last-resort signal for transport categories.
+
+Supported categories are authentication, permission, rate_limit, quota,
+conflict, validation, not_found, payload_too_large, timeout, network,
+upstream, server, schema, endpoint, aborted, stream and unknown. A 409
+conflict intentionally does not become an automatic retry: the library cannot
+infer how the application should resolve state.
+
+## Plan retries, never replay blindly
+
+An HTTP method does not prove that a request is safe to replay. Supply the
+operation's replay contract and the phase in which it failed:
+
+    context = OpenAICompatibleErrors::RetryContext.new(
+      method: "POST",
+      phase: :http_error,
+      replay_safety: :safe,
+      # caller-owned operation contract, not a guess from the verb
+      attempt: 1,
+      elapsed_ms: 350
+    )
+
+    plan = OpenAICompatibleErrors.decide_retry(error, context)
+
+    case plan.action
+    when :retry
+      schedule_retry_after(plan.delay_ms || 0) # your scheduler owns the wait
+    when :do_not_retry
+      fail_request(error)
+    when :manual_decision
+      ask_the_application_for_more_evidence
+    end
+
+retry is returned only for a transient category, known replay-safe operation,
+known phase, no observed stream output and remaining attempt/time budgets.
+do_not_retry covers permanent failures, unsafe replay, cancellation,
+completion, partial output and exhausted budgets. manual_decision means the
+evidence is incomplete or unclassified.
+
+Server Retry-After and millisecond hints are parsed without network calls.
+Duplicate hints use the longest valid delay. A malformed present hint becomes a
+bounded sentinel, so the default policy fails closed rather than replacing a
+server instruction with a short local retry. Local exponential backoff supports
+full jitter and an injectable random function for deterministic tests:
+
+    policy = OpenAICompatibleErrors::RetryPolicy.new(
+      max_attempts: 4,
+      max_elapsed_ms: 20_000,
+      jitter: :none
+    )
+    plan = OpenAICompatibleErrors.decide_retry(error, context, policy: policy)
+
+The library never sleeps, opens a socket, calls a provider or replays a
+request.
+
+## Inspect streaming replay boundaries
+
+SSEInspector consumes byte chunks incrementally. It handles CRLF/LF framing,
+UTF-8 split across network chunks, Chat Completions deltas, Responses event
+names, [DONE], provider error events and unexpected EOF. It records state only:
+
+    inspector = OpenAICompatibleErrors::SSEInspector.new
+
+    response.each_body do |chunk|
+      inspector.feed(chunk)
+      consume_chunk(chunk) # the application decides what to render
+    end
+
+    state = inspector.close
+    if state.unexpected_eof? && state.has_output
+      # The provider may already have produced billable/user-visible output.
+      raise "stream ended after partial output; do not replay automatically"
+    end
+
+For an Enumerable, the helper preserves one-at-a-time iteration and yields
+each original chunk before asking for the next:
+
+    state = OpenAICompatibleErrors::SSEInspector.inspect_each(response_enum) do |chunk|
+      render(chunk)
+    end
+
+Terminal states are done, incomplete, error and unexpected_eof. has_output is
+intentionally conservative: a false positive merely prevents an unsafe replay,
+while a false negative could duplicate output or billing. The inspector never
+stores generated text or a complete response body.
+
+## Bounded log sanitization
+
+Use sanitize_for_log for small diagnostic context, not as a data-retention
+policy:
+
+    safe = OpenAICompatibleErrors.sanitize_for_log(
+      { "provider" => "example", "api_key" => ENV["API_KEY"], "attempt" => 2 }
+    )
+
+It redacts sensitive key names and common credential formats, limits depth,
+nodes, keys, items and characters, and breaks cycles. Exception messages are
+never traversed. Keep real credentials, prompts, completions and customer
+payloads out of fixtures and logs.
+
+## Compatibility and boundaries
+
+This gem targets common OpenAI-compatible shapes used by gateways, self-hosted
+routers and SDK adapters. It is not an OpenAI product, provider certification
+or promise of complete parity with any vendor's proprietary event schema.
+Unknown data-bearing SSE events are treated conservatively because replaying
+after an unrecognized event can duplicate visible output.
+
+Use a full resilience library when you need circuit breaking, cancellation-aware
+sleep, hedging or request execution. Keep a provider SDK's native exception when
+one stable provider contract is all your application needs.
+
+## Development
+
+    bundle install
+    bundle exec rake test
+    gem build openai-compatible-errors.gemspec
+
+See CONTRIBUTING.md, SECURITY.md and RELEASING.md for the test boundary and
+token-free release process.
+
+MIT licensed.

data/RELEASING.md

@@ -0,0 +1,34 @@
+# Releasing
+
+This repository uses RubyGems.org Trusted Publishing. The release workflow
+does not store a long-lived RubyGems API key.
+
+## One-time RubyGems setup
+
+1. Sign in to RubyGems.org and open
+   https://rubygems.org/profile/oidc/pending_trusted_publishers.
+2. Create a pending publisher with:
+   - Gem name: openai-compatible-errors
+   - GitHub repository owner: airouter-dev
+   - GitHub repository name: openai-compatible-errors-ruby
+   - Workflow filename: release.yml
+   - Environment: release
+3. In the GitHub repository, ensure the release environment exists. The
+   workflow requests id-token: write only for the publishing job.
+
+RubyGems converts the pending publisher into a normal publisher after the first
+successful push and adds the account that created it as a gem owner.
+
+## Versioned release
+
+Update VERSION and CHANGELOG.md, run the complete test suite, commit the
+change, and create a matching tag:
+
+    bundle exec rake test
+    git tag -a v0.1.0 -m "Release v0.1.0"
+    git push origin main --follow-tags
+
+The tag starts .github/workflows/release.yml. The action configures a
+short-lived OIDC credential, runs the Bundler release task and waits for the
+gem to become available. Never paste a RubyGems token into source, CI logs or
+chat.

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "lib"
+  task.libs << "test"
+  task.pattern = "test/test_*.rb"
+  task.verbose = true
+end
+
+task default: :test

data/SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+Do not put API keys, prompts, completions, customer payloads or production
+tracebacks in issues or pull requests.
+
+The library is safe by default in one important way: ApiError has no raw body
+or headers field, and provider text is omitted unless the caller explicitly
+opts in. sanitize_for_log is bounded and cycle-aware, but no redactor can
+guarantee that arbitrary application data is safe to log.
+
+Report a suspected credential leak, parser denial of service, unsafe replay
+decision or release-workflow issue through a private GitHub security advisory
+at:
+
+https://github.com/airouter-dev/openai-compatible-errors-ruby/security/advisories/new
+
+Please include a minimal synthetic reproduction, affected version and impact.
+Allow time for a fix before publishing details.

data/examples/net_http.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "logger"
+require "openai_compatible_errors"
+
+# This example uses a synthetic response so it never contacts a provider.
+response = {
+  status: 429,
+  headers: {
+    "retry-after" => "1",
+    "x-request-id" => "req_example"
+  },
+  body: {
+    error: {
+      code: "rate_limit_exceeded",
+      type: "requests",
+      message: "provider-controlled detail"
+    }
+  }
+}
+
+error = OpenAICompatibleErrors.normalize_error(response)
+Logger.new($stdout).warn(error.to_log_h)
+
+context = OpenAICompatibleErrors::RetryContext.new(
+  method: "POST",
+  phase: :http_error,
+  replay_safety: :safe,
+  attempt: 1,
+  elapsed_ms: 120
+)
+puts OpenAICompatibleErrors.decide_retry(error, context).to_h

data/lib/openai_compatible_errors/error.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module OpenAICompatibleErrors
+  CATEGORIES = %i[
+    authentication
+    permission
+    rate_limit
+    quota
+    conflict
+    validation
+    not_found
+    payload_too_large
+    timeout
+    network
+    upstream
+    server
+    schema
+    endpoint
+    aborted
+    stream
+    unknown
+  ].freeze
+
+  SOURCES = %i[http httpx openai_sdk sse unknown].freeze
+
+  SAFE_MESSAGES = {
+    authentication: "The API request could not be authenticated.",
+    permission: "The API request was not permitted.",
+    rate_limit: "The API rate limit was reached.",
+    quota: "The API quota is unavailable or exhausted.",
+    conflict: "The API request conflicted with current server state.",
+    validation: "The API request was rejected as invalid.",
+    not_found: "The requested API resource was not found.",
+    payload_too_large: "The API request payload was too large.",
+    timeout: "The API request timed out.",
+    network: "The API request failed at the network boundary.",
+    upstream: "The upstream API was temporarily unavailable.",
+    server: "The API returned a server error.",
+    schema: "The API payload did not match the expected schema.",
+    endpoint: "The API endpoint was not found.",
+    aborted: "The API request was cancelled by the caller.",
+    stream: "The API stream ended with an error.",
+    unknown: "The API request failed for an unclassified reason."
+  }.freeze
+
+  # A deliberately small immutable snapshot. Raw bodies, headers, causes and
+  # tracebacks are not retained, so logging this object is safe by default.
+  class ApiError
+    attr_reader :category, :source, :status, :code, :type, :request_id,
+                :retry_after_ms, :provider_message
+
+    def initialize(category:, source:, status: nil, code: nil, type: nil,
+                   request_id: nil, retry_after_ms: nil, provider_message: nil)
+      @category = normalize_symbol(category, CATEGORIES, :unknown)
+      @source = normalize_symbol(source, SOURCES, :unknown)
+      @status = normalize_status(status)
+      @code = bounded_text(code, 256)
+      @type = bounded_text(type, 256)
+      @request_id = bounded_text(request_id, 256)
+      @retry_after_ms = normalize_delay(retry_after_ms)
+      @provider_message = bounded_text(provider_message, 2_000)
+      freeze
+    end
+
+    def message
+      SAFE_MESSAGES.fetch(@category)
+    end
+
+    def to_h(include_provider_message: false)
+      result = {
+        message: message,
+        category: @category,
+        source: @source
+      }
+      { status: @status, code: @code, type: @type, request_id: @request_id,
+        retry_after_ms: @retry_after_ms }.each do |key, value|
+        result[key] = value unless value.nil?
+      end
+      if include_provider_message && !@provider_message.nil?
+        result[:provider_message] = @provider_message
+      end
+      result.freeze
+    end
+
+    alias to_log_h to_h
+
+    def retryable_category?
+      %i[rate_limit timeout network upstream server stream].include?(@category)
+    end
+
+    def ==(other)
+      other.is_a?(ApiError) &&
+        [@category, @source, @status, @code, @type, @request_id,
+         @retry_after_ms, @provider_message] ==
+          [other.category, other.source, other.status, other.code, other.type,
+           other.request_id, other.retry_after_ms, other.provider_message]
+    end
+
+    alias eql? ==
+
+    def hash
+      [@category, @source, @status, @code, @type, @request_id,
+       @retry_after_ms, @provider_message].hash
+    end
+
+    def inspect
+      "#<#{self.class} category=#{@category.inspect} source=#{@source.inspect} " \
+        "status=#{@status.inspect} code=#{@code.inspect} type=#{@type.inspect} " \
+        "request_id=#{@request_id.inspect} retry_after_ms=#{@retry_after_ms.inspect}>"
+    end
+
+    def to_s
+      message
+    end
+
+    private
+
+    def normalize_symbol(value, allowed, fallback)
+      candidate =
+        if value.is_a?(Symbol)
+          value
+        elsif value.is_a?(String) && value.bytesize <= 64
+          value.strip.downcase.to_sym
+        end
+      allowed.include?(candidate) ? candidate : fallback
+    end
+
+    def normalize_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 normalize_delay(value)
+      return nil unless value.is_a?(Integer) && !value.is_a?(TrueClass) &&
+                        !value.is_a?(FalseClass) && value >= 0
+
+      [value, Headers::MAX_RETRY_AFTER_MS].min
+    rescue NameError
+      [value, 86_400_000].min
+    end
+
+    def bounded_text(value, limit)
+      return nil unless value.is_a?(String)
+
+      value = value.strip
+      return nil if value.empty?
+
+      result = value.bytesize > limit ? value.byteslice(0, limit).scrub : value
+      result.dup.freeze
+    end
+  end
+
+  NormalizedError = ApiError
+end

data/lib/openai_compatible_errors/headers.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "time"
+
+module OpenAICompatibleErrors
+  module Headers
+    MAX_RETRY_AFTER_MS = 86_400_000
+    MAX_HEADER_VALUE_CHARS = 512
+    REQUEST_ID_NAMES = %w[x-request-id request-id x-correlation-id trace-id].freeze
+    RETRY_NAMES = %w[retry-after retry-after-ms x-retry-after-ms].freeze
+
+    module_function
+
+    def materialize(input)
+      pairs = []
+      if input.is_a?(Hash)
+        input.each_pair { |key, value| pairs << [key, value] }
+      elsif input.respond_to?(:each_header)
+        begin
+          input.each_header { |key, value| pairs << [key, value] }
+        rescue StandardError
+          pairs = []
+        end
+      elsif input.respond_to?(:each_pair)
+        begin
+          input.each_pair { |key, value| pairs << [key, value] }
+        rescue StandardError
+          pairs = []
+        end
+      end
+
+      result = Hash.new { |hash, key| hash[key] = [] }
+      pairs.each do |key, value|
+        name = key.to_s.strip.downcase
+        next unless name.match?(/\A[a-z0-9][a-z0-9_-]{0,127}\z/)
+
+        values = value.is_a?(Array) ? value : [value]
+        values.each do |item|
+          text = item.is_a?(String) ? item : item.to_s
+          next if text.empty? || text.bytesize > MAX_HEADER_VALUE_CHARS
+
+          result[name] << text
+        end
+      end
+      result
+    end
+
+    def values(input, name)
+      materialize(input)[name.to_s.downcase]
+    end
+
+    def request_id(input)
+      headers = materialize(input)
+      REQUEST_ID_NAMES.each do |name|
+        headers[name].each do |candidate|
+          value = candidate.strip
+          next unless value.match?(/\A[A-Za-z0-9][A-Za-z0-9._:\/-]{0,255}\z/)
+          next if value.match?(/bearer|api[_ -]?key|secret|token/i)
+
+          return value
+        end
+      end
+      nil
+    end
+
+    # Returns a bounded delay. A malformed present hint returns the maximum
+    # sentinel so a conservative retry policy fails closed.
+    def retry_after_ms(input, now: Time.now)
+      headers = materialize(input)
+      candidates = []
+      malformed = false
+      RETRY_NAMES.each do |name|
+        headers[name].each do |value|
+          parsed =
+            if name.end_with?("-ms")
+              parse_milliseconds(value)
+            else
+              parse_retry_after(value, now: now)
+            end
+          if parsed.nil?
+            malformed = true
+          else
+            candidates << parsed
+          end
+        end
+      end
+      return candidates.max unless candidates.empty?
+      malformed ? MAX_RETRY_AFTER_MS : nil
+    end
+
+    def parse_milliseconds(value)
+      return nil unless value.match?(/\A\d{1,12}\z/)
+
+      [value.to_i, MAX_RETRY_AFTER_MS].min
+    end
+
+    def parse_retry_after(value, now:)
+      if value.match?(/\A\d{1,8}\z/)
+        return [value.to_i * 1_000, MAX_RETRY_AFTER_MS].min
+      end
+      return nil unless value.bytesize <= 128
+
+      begin
+        seconds = Time.httpdate(value).to_f - now.to_f
+        return [[(seconds * 1_000).ceil, 0].max, MAX_RETRY_AFTER_MS].min
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end