gigachat-ruby 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b0549b3d0c559ef154e36cfaa3fed6592068cdfbcf50e5fa29bda9d9167d8e2
-  data.tar.gz: 4264f7de916a13286744a74e2a8dec78c7e1b766dfcc0237d377352094b8ee34
+  metadata.gz: cd0ada64b65b7605a1c98a61e4b3615e3570c1614b9b528a0aafb84549134cfa
+  data.tar.gz: 3262d0b82317e3306d009cd2f2f5315a7cbe1aa2e8c37401fdbc976edefdcc50
 SHA512:
-  metadata.gz: 51bb690904f272e089051596a55d8d2f6cf558e96c5c9082cf10065a2c5c7bdef069602c556e6a37c507e5b8c6702f0a370dab263c8800eb5b9c94aa4212098d
-  data.tar.gz: f27d1bfa89ed131c70f46633927fbd90e446f72c183675487cdf52eb841e003dbff825ebdf899bc69b19330d1b5de86e2bbfdcfa17d7cd6c473d3ebc27f00262
+  metadata.gz: 7e166d6b863e049ca5004ea431538b0e9b1db681ad8833789f52cba3049c5eef0cf45ff1a6e5719fd0cd250247e2a029c840ddc96d7ed0f0942b1ddc9a33f170
+  data.tar.gz: 02bb5c155c2b9528d7644ab9fcda43d83c8e1fdfeb407ad1fce673833a1a69a335ed4518327b17b67539d6b651f56d476f6bfae1bb991aa1ef800912b43e8e00

data/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.2] - 2026-10-04
+
+### Fixed
+
+- Chat streams (v1 and v2) now arrive as they are generated. GigaChat delivers server-sent events incrementally
+  only over HTTP/2 and buffers the whole answer over HTTP/1.1, which is all Net::HTTP (Faraday's default
+  adapter) speaks, so every event used to arrive at once after the answer was complete.
+- Stopping a stream early (breaking out of the block, or an exception from it) resets the connection, so
+  GigaChat stops generating.
+
+### Changed
+
+- Chat streams use [httpx](https://gitlab.com/os85/httpx) over HTTP/2; every other request stays on Faraday.
+  New runtime dependency: `httpx ~> 1.8`. Proxies from `HTTP(S)_PROXY` are not applied to streams.
+
+## [0.1.1] - 2026-10-02
+
+### Added
+
+- `GigaChat::PaymentRequiredError` for HTTP 402 (token balance exhausted). The OpenAPI spec doesn't list
+  this status, but the API returns it in practice.
+
 ## [0.1.0] - 2026-10-02
 
 ### Added

data/README.md

@@ -126,7 +126,7 @@ stream.text.each { print it } # text deltas only
 stream.response               # accumulated completion
 ```
 
-Breaking out of the block closes the connection.
+Streams run over HTTP/2 (through [httpx](https://gitlab.com/os85/httpx)): GigaChat delivers events as they are generated only over HTTP/2, while over HTTP/1.1 the whole answer arrives at once. Breaking out of the block (or raising from it) aborts the request and closes the connection, so GigaChat stops generating. Proxies from `HTTP(S)_PROXY` are not applied to streams.
 
 ### Function calling
 
@@ -248,6 +248,7 @@ The API's `method` field is exposed as `batch_method`, because a `method` reader
 |---|---|
 | 400 | `GigaChat::BadRequestError` |
 | 401 | `GigaChat::AuthenticationError` |
+| 402 | `GigaChat::PaymentRequiredError` (token balance exhausted) |
 | 403 | `GigaChat::PermissionDeniedError` |
 | 404 | `GigaChat::NotFoundError` |
 | 413 | `GigaChat::RequestEntityTooLargeError` |

data/lib/gigachat/client.rb

@@ -55,26 +55,23 @@ module GigaChat
     def chat_v2_url = @transport.chat_v2_url
 
     # @api private
-    # Streaming POST that yields raw SSE bytes and response headers. Retries and the 401 replay happen
-    # only until the first byte reaches the caller, so output is never duplicated.
+    # Streaming POST (HTTP/2, see Internal::Transport#stream) that yields raw SSE bytes and response
+    # headers. Retries and the 401 replay happen only until the first byte reaches the caller, so output is
+    # never duplicated; exceptions from the block surface unchanged.
     def request_stream(path:, body:, request_options: {}, &on_chunk)
       options = check_request_options(request_options)
       headers = STREAM_HEADERS.merge(options[:headers] || {})
       payload = JSON.generate(body)
       delivered = false
       fresh = -> { !delivered }
-      escape = Object.new
-      failure = catch(escape) do
-        return retry_policy(options).run(method: :post, retry_if: fresh) do
-          authenticated(headers, replay: fresh) do |signed|
-            stream_once(path, payload, signed, options) do |chunk, response_headers|
-              delivered = true
-              deliver(on_chunk, chunk, response_headers, escape)
-            end
+      retry_policy(options).run(method: :post, retry_if: fresh) do
+        authenticated(headers, replay: fresh) do |signed|
+          stream_once(path, payload, signed, options) do |chunk, response_headers|
+            delivered = true
+            on_chunk.call(chunk, response_headers)
           end
         end
       end
-      raise failure
     end
 
     # Low-level call with auth, retries and error mapping; also the escape hatch for undocumented endpoints.
@@ -149,47 +146,38 @@ module GigaChat
 
     def authorization(token) = token ? { "Authorization" => "Bearer #{token.access_token}" } : {}
 
-    # With on_data set, Faraday leaves response.body empty, so error bodies are collected here.
+    # The head arrives before any body, so a non-2xx or non-SSE response is buffered and raised here, while
+    # the retry and the 401 replay may still resend the request.
     def stream_once(path, payload, headers, options)
-      sse = nil
-      seen = nil
+      status = nil
+      response_headers = nil
       error_body = +"".b
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      on_data = proc do |chunk, _bytes, env|
-        seen = env
-        sse = env.status.between?(200, 299) && event_stream?(env.response_headers) if sse.nil?
-        if sse
-          yield chunk, env.response_headers
+      @transport.stream(path, body: payload, headers:, timeout: options[:timeout]) do |event, *args|
+        if event == :head
+          status, response_headers = args
+        elsif sse?(status, response_headers)
+          yield args.first, response_headers
         else
-          error_body << chunk.b
+          error_body << args.first.b
         end
       end
-      response = perform(method: :post, url: path, body: payload, headers:, options:, on_data:)
-      seen = nil # perform has logged the request
-      sse = response.success? && event_stream?(response.headers) if sse.nil?
-      raise_stream_failure(response, error_body) unless sse
-      response
+      raise_stream_failure(status, response_headers, error_body) unless sse?(status, response_headers)
     ensure
-      # A finished stream stops with throw (or the caller breaks), which unwinds past perform's log line.
-      log(:post, path, seen.status, seen.response_headers, started) if seen
+      # Logged here so a stream that stops early (the caller breaks or [DONE] ends it) is logged too.
+      log(:post, path, status, response_headers, started) if status
     end
 
-    # Faraday's adapter rescues IOError and SystemCallError raised inside on_data and re-raises them as
-    # ConnectionFailed. Caller exceptions are thrown past it so they surface unchanged and are never retried.
-    def deliver(on_chunk, chunk, headers, escape)
-      on_chunk.call(chunk, headers)
-    rescue StandardError => e
-      throw escape, e
-    end
+    def sse?(status, headers) = status&.between?(200, 299) && event_stream?(headers)
 
     def event_stream?(headers) = headers["content-type"].to_s.start_with?("text/event-stream")
 
-    def raise_stream_failure(response, error_body)
+    def raise_stream_failure(status, headers, error_body)
       body = Internal::Util.parse_json(error_body)
-      raise APIError.for(status: response.status, body:, headers: response.headers) unless response.success?
+      raise APIError.for(status:, body:, headers:) unless status.between?(200, 299)
 
-      raise APIError.new(status: response.status, body:, headers: response.headers,
-                         message: "Expected text/event-stream, got #{response.headers["content-type"].inspect}")
+      raise APIError.new(status:, body:, headers:,
+                         message: "Expected text/event-stream, got #{headers["content-type"].inspect}")
     end
 
     def perform(method:, url:, headers:, options:, query: nil, body: nil, on_data: nil)

data/lib/gigachat/errors.rb

@@ -27,9 +27,9 @@ module GigaChat
       return ServerError if status >= 500
 
       {
-        400 => BadRequestError, 401 => AuthenticationError, 403 => PermissionDeniedError,
-        404 => NotFoundError, 413 => RequestEntityTooLargeError, 422 => UnprocessableEntityError,
-        429 => RateLimitError
+        400 => BadRequestError, 401 => AuthenticationError, 402 => PaymentRequiredError,
+        403 => PermissionDeniedError, 404 => NotFoundError, 413 => RequestEntityTooLargeError,
+        422 => UnprocessableEntityError, 429 => RateLimitError
       }.fetch(status, APIError)
     end
 
@@ -60,6 +60,9 @@ module GigaChat
 
   class AuthenticationError < APIError; end
 
+  # 402: the token balance is exhausted. Not in the OpenAPI spec, but returned in practice.
+  class PaymentRequiredError < APIError; end
+
   class PermissionDeniedError < APIError; end
 
   class NotFoundError < APIError; end

data/lib/gigachat/internal/retry_policy.rb

@@ -53,7 +53,7 @@ module GigaChat
       def retryable?(error, method)
         case error
         when APITimeoutError then method.to_s.casecmp?("get") # a timed-out POST may already be billed
-        when APIConnectionError then error.cause.is_a?(Faraday::ConnectionFailed) # never retry TLS errors
+        when APIConnectionError then Transport.retryable_connection_error?(error.cause) # never retry TLS errors
         else RETRYABLE_STATUSES.include?(error.status)
         end
       end

data/lib/gigachat/internal/transport.rb

@@ -2,13 +2,25 @@
 
 module GigaChat
   module Internal
-    # Builds the Faraday connections (API and OAuth) with TLS settings and default headers.
+    # Builds the Faraday connections (API and OAuth) with TLS settings and default headers, and runs chat
+    # streams over HTTP/2 with httpx: GigaChat's gateway delivers server-sent events incrementally only
+    # over HTTP/2 and buffers the whole response over HTTP/1.1, the only version Net::HTTP speaks.
     class Transport
       CA_FILE = File.expand_path("../certs/russian_trusted_root_ca.pem", __dir__)
       USER_AGENT = "gigachat-ruby/#{VERSION} ruby/#{RUBY_VERSION}".freeze
       X_HEADERS = %w[x-request-id x-session-id x-client-id].freeze
       TLS_HINT = "GigaChat certificates chain to the Russian Trusted Root CA; " \
                  "see the TLS section of the gigachat-ruby README"
+      # Failures before a connection carries the request; TLS errors are left out on purpose.
+      RETRYABLE_CONNECTION_ERRORS = [
+        Faraday::ConnectionFailed, HTTPX::ConnectionError, HTTPX::ResolveError, SocketError, SystemCallError, IOError
+      ].freeze
+
+      # Raised into the httpx fiber when the caller stops reading early. httpx's error path resets the
+      # connection, whereas unwinding past it closes HTTP/2 gracefully and leaves the stream (and GigaChat's
+      # generation) running.
+      class Aborted < StandardError; end
+      private_constant :Aborted
 
       def self.wrap_errors
         yield
@@ -20,6 +32,8 @@ module GigaChat
         raise APIConnectionError, e.message
       end
 
+      def self.retryable_connection_error?(error) = RETRYABLE_CONNECTION_ERRORS.any? { error.is_a?(it) }
+
       def self.x_headers(headers) = X_HEADERS.to_h { [it, headers[it]] }.compact
 
       @cert_stores = {}
@@ -65,8 +79,60 @@ module GigaChat
         @cert_store ||= self.class.cert_store(bundled_ca: config.bundled_ca, ca_bundle_file: config.ca_bundle_file)
       end
 
+      # POSTs over HTTP/2 and yields `:head, status, headers`, then `:chunk, bytes` for each body chunk;
+      # returns once the body is complete. httpx runs in its own fiber, so the block never runs inside
+      # httpx: an exception, break or throw from it aborts the request and resets the connection.
+      def stream(path, body:, headers:, timeout: nil)
+        fiber = stream_fiber(URI.join(base_url, path).to_s, body, headers, timeout || config.timeout)
+        finished = false
+        loop do
+          event, *args = fiber.resume
+          next yield(event, *args) unless event == :done
+
+          finished = true
+          response = args.first
+          raise_stream_error(response.error) if response.is_a?(HTTPX::ErrorResponse)
+          return response
+        end
+      ensure
+        abort_stream(fiber) unless finished
+      end
+
       private
 
+      def stream_session = @stream_session ||= HTTPX.plugin(:callbacks).with(ssl: stream_ssl, headers: default_headers)
+
+      # Callbacks go on a per-request branch: registering them on the shared session would leak them into
+      # every later request.
+      def stream_fiber(url, body, headers, timeout)
+        timeouts = { connect_timeout: config.open_timeout, read_timeout: timeout, write_timeout: timeout }
+        session = stream_session
+                  .with(timeout: timeouts)
+                  .on_response_started { |_request, response| Fiber.yield([:head, response.status, response.headers]) }
+                  .on_response_body_chunk { |_request, _response, chunk| Fiber.yield([:chunk, chunk]) }
+        Fiber.new { [:done, session.post(url, body:, headers:)] }
+      end
+
+      def abort_stream(fiber)
+        fiber.raise(Aborted) if fiber&.alive?
+      rescue Aborted
+        nil
+      end
+
+      def raise_stream_error(error)
+        case error
+        when HTTPX::TimeoutError then raise APITimeoutError, error.message, cause: error
+        when OpenSSL::SSL::SSLError then raise APIConnectionError, "#{error.message}. #{TLS_HINT}", cause: error
+        else raise APIConnectionError, error.message, cause: error
+        end
+      end
+
+      def stream_ssl
+        options = ssl_options(true)
+        { verify_mode: options[:verify] ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE,
+          cert_store: options[:cert_store], cert: options[:client_cert], key: options[:client_key] }.compact
+      end
+
       def connection(url, client_cert: false)
         request = { timeout: config.timeout, open_timeout: config.open_timeout, write_timeout: config.timeout }
         Faraday.new(url:, headers: default_headers, ssl: ssl_options(client_cert), request:) do |f|

data/lib/gigachat/version.rb

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

data/lib/gigachat.rb

@@ -2,6 +2,7 @@
 
 require "faraday"
 require "faraday/multipart"
+require "httpx"
 require "json"
 require "openssl"
 require "securerandom"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gigachat-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Aleksandr Dryzhuk
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: httpx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement