rails-openrouter 0.2.0

data/lib/openrouter/structure.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # A thin, dot-accessible wrapper around a decoded JSON object.
+  #
+  # The API surface is intentionally permissive: unknown or absent keys return
+  # nil rather than raising, because nearly every field in a streaming delta is
+  # optional (`chunk.choices.first.delta.content` is nil on the role-only chunk
+  # and on the final finish_reason chunk).
+  #
+  #   completion.choices.first.message.content  #=> "Hello"
+  #   completion[:usage][:total_tokens]         #=> 42
+  #   completion.to_h                           #=> plain Hash, symbol keys
+  class Structure
+    include Enumerable
+
+    def self.wrap(value)
+      case value
+      when Structure then value
+      when Hash then new(value)
+      when Array then value.map { |item| wrap(item) }
+      else value
+      end
+    end
+
+    def initialize(data = {})
+      raise ArgumentError, "expected a Hash, got #{data.class}" unless data.is_a?(Hash)
+
+      @data = data
+    end
+
+    def [](key)
+      symbol = key.to_sym if key.respond_to?(:to_sym)
+      value = if symbol && @data.key?(symbol)
+                @data[symbol]
+              else
+                @data[key.to_s]
+              end
+      self.class.wrap(value)
+    end
+
+    def fetch(key, *default, &block)
+      value = @data.fetch(key.to_sym) { @data.fetch(key.to_s, *default, &block) }
+      self.class.wrap(value)
+    end
+
+    def dig(*keys)
+      keys.reduce(self) do |acc, key|
+        case acc
+        when Structure, Hash then acc[key]
+        when Array then key.is_a?(Integer) ? Structure.wrap(acc[key]) : nil
+        else nil
+        end
+      end
+    end
+
+    def key?(key)
+      @data.key?(key.to_sym) || @data.key?(key.to_s)
+    end
+    alias has_key? key?
+    alias include? key?
+
+    def keys
+      @data.keys
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @data.each { |key, value| block.call(key, self.class.wrap(value)) }
+      self
+    end
+
+    def empty?
+      @data.empty?
+    end
+
+    def to_h
+      @data
+    end
+    alias to_hash to_h
+
+    def as_json
+      @data
+    end
+
+    def to_json(*args)
+      @data.to_json(*args)
+    end
+
+    def ==(other)
+      case other
+      when Structure then to_h == other.to_h
+      when Hash then to_h == other
+      else false
+      end
+    end
+    alias eql? ==
+
+    def hash
+      @data.hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@data.inspect}>"
+    end
+    alias to_s inspect
+
+    def pretty_print(pp)
+      pp.text("#<#{self.class.name} ")
+      pp.pp(@data)
+      pp.text(">")
+    end
+
+    # Ruby asks about these when it wants an implicit conversion. Answering
+    # "yes, and here is nil" makes a Structure blow up in surprising places
+    # (Array(), string interpolation, flatten), so they stay undefined.
+    PROTOCOL_METHODS = %i[to_ary to_str to_int to_io to_proc coerce].freeze
+
+    # Reports only what is actually in the payload. Absent keys still answer
+    # through #method_missing, but duck-typing checks get an honest answer.
+    def respond_to_missing?(name, include_private = false)
+      key = name.to_s
+      return false if key.end_with?("=", "!")
+
+      key?(key.chomp("?")) || super
+    end
+
+    def method_missing(name, *args)
+      return super if PROTOCOL_METHODS.include?(name)
+
+      key = name.to_s
+      if key.end_with?("?")
+        value = self[key.chomp("?")]
+        return !!value && value != 0 && value != ""
+      end
+
+      raise NoMethodError, "undefined method `#{name}' for #{inspect}" unless args.empty?
+
+      self[key]
+    end
+  end
+end

data/lib/openrouter/transport.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module OpenRouter
+  # Net::HTTP transport: JSON in, JSON or server-sent events out, with retries.
+  #
+  # Deliberately dependency-free — the gem installs with nothing but the
+  # standard library, which matters for a client people drop into an existing
+  # Rails app that already pins its own HTTP stack.
+  class Transport
+    RETRIABLE_STATUSES = [408, 409, 429, 500, 502, 503, 504].freeze
+
+    RETRIABLE_EXCEPTIONS = [
+      Errno::ECONNABORTED, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH, Errno::EPIPE, Errno::ETIMEDOUT,
+      EOFError, IOError, SocketError, Timeout::Error,
+      Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+      OpenSSL::SSL::SSLError
+    ].freeze
+
+    TIMEOUT_EXCEPTIONS = [Net::OpenTimeout, Net::ReadTimeout, Timeout::Error].freeze
+
+    # Handle on the socket behind a live stream, so a consumer can hang up early.
+    class Connection
+      def initialize
+        @mutex = Mutex.new
+        @http = nil
+        @closed = false
+      end
+
+      def attach(http)
+        @mutex.synchronize do
+          raise StreamClosedError, "stream was closed before it started" if @closed
+
+          @http = http
+        end
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def close
+        http = nil
+        @mutex.synchronize do
+          return false if @closed
+
+          @closed = true
+          http = @http
+          @http = nil
+        end
+
+        begin
+          http.finish if http.respond_to?(:started?) && http.started?
+        rescue StandardError
+          nil # the socket is going away either way
+        end
+        true
+      end
+    end
+
+    def initialize(base_url:, headers: {}, timeout: 600, open_timeout: 10, write_timeout: 30,
+                   max_retries: 2, initial_retry_delay: 0.5, max_retry_delay: 8.0,
+                   logger: nil, debug_output: nil, sleeper: nil)
+      @base_uri = URI.parse(base_url.to_s.sub(%r{/+\z}, "") + "/")
+      @headers = stringify_headers(headers)
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @write_timeout = write_timeout
+      @max_retries = max_retries.to_i
+      @initial_retry_delay = initial_retry_delay
+      @max_retry_delay = max_retry_delay
+      @logger = logger
+      @debug_output = debug_output
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    attr_reader :base_uri, :max_retries
+
+    # Performs a request and returns the decoded body as a Hash.
+    #
+    # `form` sends multipart/form-data instead of JSON (see Net::HTTPHeader#set_form).
+    # `raw` returns the response body as bytes, for endpoints that answer with a
+    # file rather than JSON.
+    def request(method, path, body: nil, form: nil, query: nil, headers: {}, timeout: nil, raw: false)
+      uri = build_uri(path, query)
+
+      with_retries do
+        http = build_http(uri, timeout: timeout)
+        response =
+          begin
+            http.start { |connection| connection.request(build_request(method, uri, body, headers, form)) }
+          rescue *RETRIABLE_EXCEPTIONS => e
+            raise connection_error(e)
+          end
+
+        raw ? raw_response(response) : parse_response(response)
+      end
+    end
+
+    # Performs a streaming request. Returns [Enumerator, Connection]; nothing
+    # touches the network until the enumerator is first advanced.
+    def stream_request(method, path, body: nil, query: nil, headers: {}, timeout: nil)
+      uri = build_uri(path, query)
+      headers = headers.merge("Accept" => "text/event-stream", "Cache-Control" => "no-cache")
+      connection = Connection.new
+
+      enumerator = Enumerator.new do |yielder|
+        attempt = 0
+        started = false
+
+        begin
+          perform_stream(method, uri, body, headers, timeout, connection) do |payload|
+            started = true
+            yielder << payload
+          end
+        rescue APIConnectionError, APIError => e
+          # Once chunks have reached the caller a retry would duplicate output,
+          # so only retry a stream that never produced anything.
+          raise e if started || connection.closed? || !retriable?(e) || attempt >= @max_retries
+
+          log_retry(e, attempt)
+          @sleeper.call(retry_delay(attempt, e))
+          attempt += 1
+          retry
+        ensure
+          connection.close
+        end
+      end
+
+      [enumerator, connection]
+    end
+
+    private
+
+    def perform_stream(method, uri, body, headers, timeout, connection)
+      http = build_http(uri, timeout: timeout)
+      connection.attach(http)
+
+      http.start do |session|
+        session.request(build_request(method, uri, body, headers)) do |response|
+          status = response.code.to_i
+          unless (200..299).cover?(status)
+            raise APIError.from_response(
+              status: status,
+              body: safe_read_body(response),
+              headers: normalize_headers(response)
+            )
+          end
+
+          parser = SSEParser.new
+
+          catch(:openrouter_stream_end) do
+            response.read_body do |bytes|
+              throw :openrouter_stream_end if connection.closed?
+
+              parser.feed(bytes) do |event|
+                handle_event(event) { |payload| yield payload }
+              end
+            end
+
+            parser.finish { |event| handle_event(event) { |payload| yield payload } }
+          end
+        end
+      end
+    rescue *RETRIABLE_EXCEPTIONS => e
+      raise connection_error(e)
+    end
+
+    def handle_event(event)
+      return if event.comment?
+      throw :openrouter_stream_end if event.done?
+
+      payload = decode_event_data(event.data)
+      yield payload if payload
+    end
+
+    def decode_event_data(data)
+      data = data.to_s
+      return nil if data.empty?
+
+      payload =
+        begin
+          JSON.parse(data, symbolize_names: true)
+        rescue JSON::ParserError
+          nil
+        end
+      return nil unless payload.is_a?(Hash)
+
+      raise error_from_payload(payload) if payload[:error]
+
+      payload
+    end
+
+    def error_from_payload(payload)
+      error = payload[:error]
+      status = error.is_a?(Hash) && error[:code].is_a?(Integer) ? error[:code] : 500
+      APIError.from_response(status: status, body: payload)
+    end
+
+    def with_retries
+      attempt = 0
+
+      begin
+        yield
+      rescue APIConnectionError, APIError => e
+        raise e unless retriable?(e) && attempt < @max_retries
+
+        log_retry(e, attempt)
+        @sleeper.call(retry_delay(attempt, e))
+        attempt += 1
+        retry
+      end
+    end
+
+    def retriable?(error)
+      case error
+      when APIConnectionError then true
+      when APIError then RETRIABLE_STATUSES.include?(error.status.to_i)
+      else false
+      end
+    end
+
+    def retry_delay(attempt, error)
+      after = retry_after_seconds(error)
+      return [after, @max_retry_delay].min if after
+
+      delay = [@initial_retry_delay * (2**attempt), @max_retry_delay].min
+      # Full-ish jitter, so a fleet of workers does not retry in lockstep.
+      delay * (0.75 + (rand * 0.5))
+    end
+
+    def retry_after_seconds(error)
+      headers = error.respond_to?(:headers) ? error.headers : nil
+      return nil unless headers.is_a?(Hash)
+
+      value = headers["retry-after"]
+      return nil if value.nil?
+      return value.to_f if value.to_s.match?(/\A\d+(\.\d+)?\z/)
+
+      begin
+        seconds = Time.parse(value.to_s) - Time.now
+        seconds.positive? ? seconds : nil
+      rescue StandardError
+        nil
+      end
+    end
+
+    def log_retry(error, attempt)
+      return unless @logger
+
+      @logger.warn("[openrouter] retrying after #{error.class}: #{error.message} (attempt #{attempt + 1}/#{@max_retries})")
+    end
+
+    def raw_response(response)
+      status = response.code.to_i
+      return response.body.to_s if (200..299).cover?(status)
+
+      raise APIError.from_response(status: status, body: response.body, headers: normalize_headers(response))
+    end
+
+    def parse_response(response)
+      status = response.code.to_i
+      headers = normalize_headers(response)
+      raw = response.body
+
+      unless (200..299).cover?(status)
+        raise APIError.from_response(status: status, body: raw, headers: headers)
+      end
+
+      return {} if raw.nil? || raw.to_s.strip.empty?
+
+      payload =
+        begin
+          JSON.parse(raw, symbolize_names: true)
+        rescue JSON::ParserError => e
+          raise APIError.new(
+            "Could not parse response as JSON: #{e.message}",
+            status: status, body: raw, headers: headers
+          )
+        end
+
+      # A 200 can still carry an error envelope instead of a completion.
+      if payload.is_a?(Hash) && payload[:error]
+        error = error_from_payload(payload)
+        raise APIError.from_response(status: error.status, body: payload, headers: headers)
+      end
+
+      payload
+    end
+
+    def build_uri(path, query)
+      uri = @base_uri.merge(path.to_s.sub(%r{\A/+}, ""))
+      params = compact_query(query)
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def compact_query(query)
+      return {} unless query.is_a?(Hash)
+
+      query.reject { |_key, value| value.nil? }
+    end
+
+    def build_http(uri, timeout: nil)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @open_timeout
+      http.read_timeout = timeout || @timeout
+      http.write_timeout = @write_timeout if http.respond_to?(:write_timeout=)
+      http.set_debug_output(@debug_output) if @debug_output
+      http
+    end
+
+    REQUEST_CLASSES = {
+      "get" => Net::HTTP::Get,
+      "post" => Net::HTTP::Post,
+      "put" => Net::HTTP::Put,
+      "patch" => Net::HTTP::Patch,
+      "delete" => Net::HTTP::Delete
+    }.freeze
+
+    def build_request(method, uri, body, headers, form = nil)
+      klass = REQUEST_CLASSES.fetch(method.to_s.downcase) do
+        raise ArgumentError, "unsupported HTTP method: #{method}"
+      end
+
+      request = klass.new(uri)
+      @headers.merge(stringify_headers(headers)).each do |key, value|
+        request[key] = value.to_s unless value.nil?
+      end
+
+      if form
+        # A retry re-reads the same IOs, so rewind before handing them over.
+        form.each { |(_name, value, _opts)| value.rewind if value.respond_to?(:rewind) }
+        request.set_form(form, "multipart/form-data")
+      elsif body
+        request["Content-Type"] ||= "application/json"
+        request.body = body.is_a?(String) ? body : JSON.generate(body)
+      end
+
+      request
+    end
+
+    def safe_read_body(response)
+      response.read_body
+    rescue StandardError
+      nil
+    end
+
+    def connection_error(error)
+      if TIMEOUT_EXCEPTIONS.any? { |klass| error.is_a?(klass) }
+        APITimeoutError.new("Request timed out: #{error.message}", original_error: error)
+      else
+        APIConnectionError.new("Connection error: #{error.message}", original_error: error)
+      end
+    end
+
+    def normalize_headers(response)
+      response.each_header.to_h { |key, value| [key.to_s.downcase, value] }
+    rescue StandardError
+      {}
+    end
+
+    def stringify_headers(headers)
+      (headers || {}).each_with_object({}) { |(key, value), memo| memo[key.to_s] = value }
+    end
+  end
+end

data/lib/openrouter/version.rb

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

data/lib/openrouter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "openrouter/version"
+require_relative "openrouter/errors"
+require_relative "openrouter/structure"
+require_relative "openrouter/attachment"
+require_relative "openrouter/content"
+require_relative "openrouter/message"
+require_relative "openrouter/sse"
+require_relative "openrouter/accumulator"
+require_relative "openrouter/stream"
+require_relative "openrouter/transport"
+require_relative "openrouter/resources/chat"
+require_relative "openrouter/resources/models"
+require_relative "openrouter/resources/files"
+require_relative "openrouter/client"
+
+# Ruby client for the OpenRouter API, with first-class streaming.
+#
+#   OpenRouter.configure do |config|
+#     config.api_key = ENV["OPENROUTER_API_KEY"]
+#     config.app_name = "My App"
+#     config.site_url = "https://example.com"
+#   end
+#
+#   OpenRouter.chat.completions.stream(
+#     model: "anthropic/claude-sonnet-4.5",
+#     messages: [{ role: "user", content: "Write a haiku about sockets" }]
+#   ).each_text { |text| print(text) }
+module OpenRouter
+  # Process-wide defaults for clients built without explicit arguments.
+  class Configuration
+    attr_accessor :api_key, :base_url, :site_url, :app_name, :default_model,
+                  :timeout, :open_timeout, :write_timeout, :max_retries,
+                  :default_headers, :default_query, :extra_body, :logger, :debug_output,
+                  :max_attachment_bytes
+
+    def initialize
+      @base_url = nil
+      @timeout = 600        # generous: a long completion holds the socket open
+      @open_timeout = 10
+      @write_timeout = 30
+      @max_retries = 2
+      @default_headers = {}
+      @default_query = {}
+      @extra_body = {}
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      @client = nil # rebuild the shared client with the new settings
+      config
+    end
+
+    # A lazily built client using the global configuration.
+    def client
+      @client ||= Client.new
+    end
+
+    def reset!
+      @config = Configuration.new
+      @client = nil
+    end
+
+    def chat
+      client.chat
+    end
+
+    def models
+      client.models
+    end
+  end
+end

data/lib/rails-openrouter.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The gem is published as "rails-openrouter", so Bundler requires this file by
+# default. The library itself is namespaced OpenRouter and lives in
+# lib/openrouter.rb, which stays the canonical entry point:
+#
+#   require "openrouter"        # or
+#   require "rails-openrouter"  # what `gem "rails-openrouter"` loads
+require_relative "openrouter"

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: rails-openrouter
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Afshin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  A dependency-free Ruby client for OpenRouter. Chat completions, model and
+  credit endpoints, and server-sent-event streaming that accumulates chunks
+  back into a final completion, with typed errors and automatic retries.
+email:
+- afshmini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/openrouter.rb
+- lib/openrouter/accumulator.rb
+- lib/openrouter/attachment.rb
+- lib/openrouter/client.rb
+- lib/openrouter/content.rb
+- lib/openrouter/errors.rb
+- lib/openrouter/message.rb
+- lib/openrouter/resources/chat.rb
+- lib/openrouter/resources/files.rb
+- lib/openrouter/resources/models.rb
+- lib/openrouter/sse.rb
+- lib/openrouter/stream.rb
+- lib/openrouter/structure.rb
+- lib/openrouter/transport.rb
+- lib/openrouter/version.rb
+- lib/rails-openrouter.rb
+homepage: https://github.com/afshmini/rails-openrouter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/afshmini/rails-openrouter
+  changelog_uri: https://github.com/afshmini/rails-openrouter/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: Ruby client for the OpenRouter API, with first-class streaming.
+test_files: []