patron 1.0.0 → 1.1.0

data/lib/patron/session.rb

@@ -3,11 +3,14 @@
 require 'uri'
 require 'patron/error'
 require 'patron/request'
+require 'patron/header_parser'
+require 'patron/response_head'
 require 'patron/response_decoding'
 require 'patron/response'
+require 'patron/response_stream'
+require 'patron/transfer_stats'
 require 'patron/session_ext'
 require 'patron/util'
-require 'patron/header_parser'
 require 'patron/compat'
 
 module Patron
@@ -126,6 +129,13 @@ module Patron
     # @see low_speed_time
     attr_accessor :low_speed_limit
 
+    # @return [Numeric, nil] how long to wait for the next piece of the response, in seconds,
+    #    counted from the previous one. Unlike #timeout it does not bound the whole transfer,
+    #    which makes it the one to use for streams. Defaults to nil, no limit. Exceeding it
+    #    raises Patron::TimeoutError.
+    # @see Patron::Request#read_timeout=
+    attr_accessor :read_timeout
+
     # @return [#call, nil] callable object that will be called with 4 arguments
     #    during request/response execution - `dltotal`, `dlnow`, `ultotal`, `ulnow`.
     #    All these arguments are in bytes. Returning `false` from the callback aborts the
@@ -208,8 +218,8 @@ module Patron
     end
 
     # Retrieve the contents of the specified +url+ as with #get, but the
-    # content at the URL is downloaded directly into the specified file. The file will be accessed
-    # by libCURL bypassing the Ruby runtime entirely.
+    # content at the URL is downloaded directly into the specified file. The body is streamed
+    # into the file through one reused buffer, see #stream.
     #
     # Note that when using this option, the Response object will have ++nil++ as the body, and you
     # will need to read your target file for access to the body string).
@@ -247,9 +257,10 @@ module Patron
     # unline ++post++, a Hash is not accepted as the ++data++ argument.
     #
     # @param url[String] the URL to fetch
-    # @param data[#to_s, #to_path] an object that can be converted to a String
-    #   to create the request body, or that responds to #to_path to upload the
-    #   entire request body from that file
+    # @param data[#to_s, #to_path, #read] an object that can be converted to a String
+    #   to create the request body, that responds to #to_path to upload the
+    #   entire request body from that file, or that responds to #read to stream
+    #   the request body from it (see Request#upload_data=)
     # @param headers[Hash] the hash of header keys to values
     # @return [Patron::Response]
     def put(url, data, headers = {})
@@ -260,9 +271,10 @@ module Patron
     # unline ++post++, a Hash is not accepted as the ++data++ argument.
     #
     # @param url[String] the URL to fetch
-    # @param data[#to_s, #to_path] an object that can be converted to a String
-    #   to create the request body, or that responds to #to_path to upload the
-    #   entire request body from that file
+    # @param data[#to_s, #to_path, #read] an object that can be converted to a String
+    #   to create the request body, that responds to #to_path to upload the
+    #   entire request body from that file, or that responds to #read to stream
+    #   the request body from it (see Request#upload_data=)
     # @param headers[Hash] the hash of header keys to values
     # @return [Patron::Response]
     def patch(url, data, headers = {})
@@ -283,17 +295,15 @@ module Patron
     # Uploads the passed `data` to the specified `url` using an HTTP POST.
     #
     # @param url[String] the URL to fetch
-    # @param data[Hash, #to_s, #to_path] a Hash of form fields/values,
+    # @param data[Hash, #to_s, #to_path, #read] a Hash of form fields/values,
     #   or an object that can be converted to a String
-    #   to create the request body, or an object that responds to #to_path to upload the
-    #   entire request body from that file
+    #   to create the request body, an object that responds to #to_path to upload the
+    #   entire request body from that file, or one that responds to #read to stream
+    #   the request body from it (see Request#upload_data=)
     # @param headers[Hash] the hash of header keys to values
     # @return [Patron::Response]
     def post(url, data, headers = {})
-      if data.is_a?(Hash)
-        data = data.map { |k, v| urlencode(k.to_s) + '=' + urlencode(v.to_s) }.join('&')
-        headers = headers.merge('Content-Type' => 'application/x-www-form-urlencoded')
-      end
+      data, headers = form_encode(data, headers)
       request(:post, url, headers, data: data)
     end
 
@@ -332,19 +342,102 @@ module Patron
     end
     # @!endgroup
 
+    # @!group Streaming
+    # Performs a request and yields its response as a ResponseStream as soon as the head of the
+    # final response has arrived, before the body. The block receives the body by reading from
+    # the stream; nothing is buffered meanwhile, and a consumer that does not read holds the
+    # transfer back. When the block ends before the body does (`break`, `return`, an exception)
+    # the transfer is aborted and its connection closed; call ResponseStream#drain! first to keep it.
+    #
+    # The Session is busy for the duration of the block, so another request on it from inside
+    # the block raises Patron::Error. #timeout still bounds the whole transfer and is usually
+    # wanted at 0 here, with `read_timeout:` bounding the wait for each next piece instead.
+    #
+    # @example
+    #   stats = session.stream(:get, "/events", { "Accept" => "text/event-stream" }, timeout: 0, read_timeout: 30) do |stream|
+    #     raise "Unexpected #{stream.status}" unless stream.ok?
+    #     stream.each_line { |line| handle(line) }
+    #   end
+    #   stats.complete? #=> true
+    #
+    # @param action[#to_s] the HTTP verb
+    # @param url[String] the URL for the request
+    # @param headers[Hash] headers to send along with the request
+    # @param options[Hash] the same options as #request takes
+    # @yieldparam stream [Patron::ResponseStream] closed once the block ends
+    # @return [Patron::TransferStats] the receipt of the transfer
+    # @raise [ArgumentError] without a block
+    def stream(action, url, headers = {}, **options, &block)
+      raise ArgumentError, "Patron::Session#stream needs a block" unless block
+      run_stream(build_request(action, url, headers, **options), &block).__send__(:receipt)
+    end
+
+    # Same as #stream with a GET
+    #
+    # @param url[String] the URL to fetch
+    # @param headers[Hash] the hash of header keys to values
+    # @param options[Hash] the same options as #request takes
+    # @yieldparam stream [Patron::ResponseStream]
+    # @return [Patron::TransferStats]
+    def get_stream(url, headers = {}, **options, &block)
+      stream(:get, url, headers, **options, &block)
+    end
+
+    # Same as #stream with a PUT, sending `data` like #put does
+    #
+    # @param url[String] the URL for the request
+    # @param data[#to_s, #to_path, #read] the request body, see #put
+    # @param headers[Hash] the hash of header keys to values
+    # @param options[Hash] the same options as #request takes
+    # @yieldparam stream [Patron::ResponseStream]
+    # @return [Patron::TransferStats]
+    def put_stream(url, data, headers = {}, **options, &block)
+      stream(:put, url, headers, **options, data: data, &block)
+    end
+
+    # Same as #stream with a POST, sending `data` like #post does: a Hash is form-encoded
+    #
+    # @param url[String] the URL for the request
+    # @param data[Hash, #to_s, #to_path, #read] the request body, see #post
+    # @param headers[Hash] the hash of header keys to values
+    # @param options[Hash] the same options as #request takes
+    # @yieldparam stream [Patron::ResponseStream]
+    # @return [Patron::TransferStats]
+    def post_stream(url, data, headers = {}, **options, &block)
+      data, headers = form_encode(data, headers)
+      stream(:post, url, headers, **options, data: data, &block)
+    end
+
+    # Same as #stream with a PATCH, sending `data` like #patch does
+    #
+    # @param url[String] the URL for the request
+    # @param data[#to_s, #to_path, #read] the request body, see #patch
+    # @param headers[Hash] the hash of header keys to values
+    # @param options[Hash] the same options as #request takes
+    # @yieldparam stream [Patron::ResponseStream]
+    # @return [Patron::TransferStats]
+    def patch_stream(url, data, headers = {}, **options, &block)
+      stream(:patch, url, headers, **options, data: data, &block)
+    end
+    # @!endgroup
+
     # @!group Basic API methods
     # Send an HTTP request to the specified `url`.
     #
     # @param action[#to_s] the HTTP verb
     # @param url[String] the URL for the request
     # @param headers[Hash] headers to send along with the request
-    # @param options[Hash] any additional Request attributes, plus `:data`, `:file`, `:multipart` and `:query`
+    # @param options[Hash] any additional Request attributes, plus `:data`, `:file`, `:multipart` and `:query`.
+    #   `:data` may be a Hash, a String, or an object responding to #to_path or #read (see Request#upload_data=)
     # @see Patron::Request
     # @return [Patron::Response]
     def request(action, url, headers = {}, *positional, **options)
       # The 0.x positional options Hash is tolerated here rather than in a prepended module, since
       # sniffer and friends alias_method-chain this method and a prepend would recurse into the alias
       options = Compat.hash_to_keywords("Patron::Session#request with an options Hash", positional, options)
+      if options[:file] && !options[:multipart] && action.to_s.casecmp?("get")
+        return download(build_request(action, url, headers, **options.except(:file)), options[:file])
+      end
       handle_request(build_request(action, url, headers, **options))
     end
 
@@ -368,7 +461,8 @@ module Patron
     # @param action[String] the HTTP verb
     # @param url[#to_s] the addition to the base url component, or a complete URL
     # @param headers[Hash] a hash of headers, "Expect" will be automatically set to an empty string if not provided
-    # @param options[Hash] any overriding options (will shadow the options from the Session object)
+    # @param options[Hash] any overriding options (will shadow the options from the Session object).
+    #   `:data` may be a Hash, a String, or an object responding to #to_path or #read (see Request#upload_data=)
     # @return [Patron::Request] the request that will be passed to ++handle_request++
     def build_request(action, url, headers = {}, **options)
       # Without an empty Expect header uploads wait for a "100 Continue" that may never come
@@ -393,10 +487,47 @@ module Patron
       automatic_content_encoding timeout connect_timeout dns_cache_timeout low_speed_time low_speed_limit
       force_ipv4 max_redirects username password proxy proxy_type auth_type insecure ssl_version http_version
       cacert ssl_cert ssl_cert_type ssl_key ssl_key_password ignore_content_length buffer_size
-      download_byte_limit progress_callback
+      download_byte_limit progress_callback read_timeout
     ].freeze
     private_constant :REQUEST_ATTRIBUTES_FROM_SESSION
 
+    # The ensure is what aborts the transfer on break, return, raise, Thread#kill or Task#stop.
+    # A transfer_start that raised has cleaned up after itself - and when it raised because
+    # a stream is already open in this very fiber, transfer_finish would end that one
+    def run_stream(request)
+      head = stream = nil
+      begin
+        head = transfer_start(request)
+        status, effective_url, redirect_count, header_data = head
+        stream = ResponseStream.new(self, status: status, url: effective_url, redirect_count: redirect_count,
+                                    header_data: header_data, default_charset: default_response_charset)
+        yield stream
+      ensure
+        if stream
+          stream.__send__(:finish)
+        elsif head
+          transfer_finish
+        end
+      end
+      stream
+    end
+
+    def download(request, path)
+      File.open(path, "wb") do |file|
+        stream = run_stream(request) { |s| IO.copy_stream(s, file) }
+        stats = stream.__send__(:receipt)
+        response_class.new(url: stats.url, status: stats.status, redirect_count: stats.redirect_count,
+                           header_data: stream.__send__(:header_data), body: nil,
+                           default_charset: default_response_charset, timings: stats.timings)
+      end
+    end
+
+    def form_encode(data, headers)
+      return [data, headers] unless data.is_a?(Hash)
+      encoded = data.map { |k, v| urlencode(k.to_s) + '=' + urlencode(v.to_s) }.join('&')
+      [encoded, headers.merge('Content-Type' => 'application/x-www-form-urlencoded')]
+    end
+
     def build_url(url, query)
       base_url = self.base_url.to_s
       url = url.to_s

data/lib/patron/sse_client.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+module Patron
+
+  # A client for server-sent events (`text/event-stream`), built on Session#stream. Parses the
+  # stream by the WHATWG event stream algorithm and reconnects the way an EventSource does:
+  # after the retry interval, sending Last-Event-ID.
+  #
+  # @example
+  #   client = Patron::SSEClient.new("https://example.com/stream", headers: { "Authorization" => "Bearer ..." }, idle_timeout: 45)
+  #   client.each_event do |event|
+  #     puts event.type, event.data, event.id
+  #     break if event.type == "done"
+  #   end
+  #   client.last_event_id # to persist between process runs
+  #
+  # A client holds one stream at a time and is meant for one thread or fiber; only #close may be
+  # called from another one.
+  class SSEClient
+    # One dispatched event. `type` is "message" unless the server sent an `event:` field, `data` is
+    # the `data:` lines joined with "\n", `id` the last event ID at the time, or nil.
+    Event = Data.define(:type, :data, :id)
+
+    # Raised for a response that is not an event stream: a status other than 200 or 204, or a
+    # Content-Type other than text/event-stream. Retrying it is up to the application.
+    class UnexpectedResponse < Patron::Error
+      # @return [Integer] the HTTP status
+      attr_reader :status
+
+      # @return [Hash] the response headers
+      attr_reader :headers
+
+      # @return [String] up to the first 4 KB of the response body
+      attr_reader :body
+
+      # @param status [Integer]
+      # @param headers [Hash]
+      # @param body [String]
+      def initialize(status, headers, body)
+        @status = status
+        @headers = headers
+        @body = body
+        super("Expected a text/event-stream with status 200, got status #{status} with Content-Type #{headers.find { |k, _| k.casecmp?("Content-Type") }&.last.inspect}")
+      end
+    end
+
+    # Raised when the stream could not be reopened within `max_reconnects` attempts
+    class ReconnectsExhausted < Patron::Error; end
+
+    # Raised when an event is not valid UTF-8, which an event stream must be. The stream ends there
+    # instead of reconnecting: a server that sends garbage would send it again.
+    class InvalidEncoding < Patron::Error; end
+
+    # The WHATWG event stream parser on its own: feed it the bytes of a stream and it yields
+    # Events. SSEClient runs one of these over its connections; {SSEClient.parse} runs one over
+    # any readable. Keeps the last event ID and the retry interval the stream asked for.
+    class Parser
+      BOM = "\xEF\xBB\xBF".b.freeze
+      LINE_END_RE = /[\r\n]/n
+      private_constant :BOM, :LINE_END_RE
+
+      # @return [String, nil] the ID of the last event dispatched
+      attr_reader :last_event_id
+
+      # @return [Float, nil] seconds from the last `retry:` field, nil when there was none
+      attr_reader :retry_interval
+
+      # @param last_event_id [String, nil] the ID to start from
+      def initialize(last_event_id: nil)
+        @last_event_id = last_event_id
+        @id_buffer = last_event_id
+        @retry_interval = nil
+        reset
+      end
+
+      # Forgets the bytes and the partial event of a stream that ended, for the next one. The
+      # last event ID and the retry interval stay.
+      #
+      # @return [nil]
+      def reset
+        @pending = String.new(encoding: Encoding::BINARY)
+        @bom_checked = false
+        @data = nil
+        @event_type = nil
+      end
+
+      # Takes the next bytes of the stream and yields every event they complete.
+      #
+      # @param bytes [String] a piece of the stream, of any length and at any boundary
+      # @yieldparam event [Patron::SSEClient::Event]
+      # @return [nil]
+      # @raise [InvalidEncoding] when an event is not valid UTF-8
+      def feed(bytes, &block)
+        @pending << bytes
+
+        unless @bom_checked
+          return if @pending.bytesize < BOM.bytesize && BOM.start_with?(@pending)
+          @pending = @pending.byteslice(BOM.bytesize, @pending.bytesize) if @pending.start_with?(BOM)
+          @bom_checked = true
+        end
+
+        process_lines(&block)
+      end
+
+      # Tells the parser the stream has ended. A "\r" held back for a "\n" that never came does end
+      # its line; an event the stream ends in the middle of is not dispatched.
+      #
+      # @yieldparam event [Patron::SSEClient::Event]
+      # @return [nil]
+      def finish(&block)
+        return unless @pending.end_with?("\r")
+        @pending << "\n"
+        process_lines(&block)
+      end
+
+      private
+
+      # Takes every complete line off the pending bytes. A "\r" at the very end may be the first
+      # half of a "\r\n" whose "\n" is still on the wire, so it waits for more
+      def process_lines(&block)
+        pos = 0
+        while (line_end = @pending.byteindex(LINE_END_RE, pos))
+          if @pending.getbyte(line_end) == 13 # \r
+            break if line_end == @pending.bytesize - 1
+            terminator = @pending.getbyte(line_end + 1) == 10 ? 2 : 1
+          else
+            terminator = 1
+          end
+          process_line(@pending.byteslice(pos, line_end - pos), &block)
+          pos = line_end + terminator
+        end
+        @pending = @pending.byteslice(pos, @pending.bytesize - pos) unless pos.zero?
+        nil
+      end
+
+      def process_line(line, &block)
+        return dispatch(&block) if line.empty?
+        return if line.start_with?(":")
+
+        field, value = line.split(":", 2)
+        value = value ? value.delete_prefix(" ") : ""
+        case field
+        when "event" then @event_type = value
+        when "data" then (@data ||= []) << value
+        when "id" then @id_buffer = (value.empty? ? nil : utf8(value)) unless value.include?("\0")
+        when "retry" then @retry_interval = Integer(value, 10) / 1000.0 if value.match?(/\A\d+\z/)
+        end
+      end
+
+      def dispatch
+        @last_event_id = @id_buffer
+        if @data
+          type = @event_type.nil? || @event_type.empty? ? "message" : utf8(@event_type)
+          event = Event.new(type: type, data: utf8(@data.join("\n")), id: @last_event_id)
+          @data = nil
+          @event_type = nil
+          yield event
+        else
+          @data = nil
+          @event_type = nil
+        end
+      end
+
+      # A browser would put U+FFFD where the bad bytes are; here they end the stream, so that no
+      # garbled event gets acted on
+      def utf8(str)
+        str = str.dup.force_encoding(Encoding::UTF_8)
+        raise InvalidEncoding, "The event stream is not valid UTF-8" unless str.valid_encoding?
+        str.freeze
+      end
+    end
+
+    BODY_EXCERPT_SIZE = 4096
+    CHUNK_SIZE = 16 * 1024
+    private_constant :BODY_EXCERPT_SIZE, :CHUNK_SIZE
+
+    # Parses an event stream from any readable and yields its events, for the streams SSEClient
+    # does not open itself: the response to a POST, a file, a socket. Reads with `readpartial`
+    # until EOFError and returns when the stream ends or the block breaks. Nothing about the
+    # response is checked here, that is the caller's job.
+    #
+    # @example An LLM completion
+    #   session.post_stream("/v1/chat/completions", body.to_json, headers) do |stream|
+    #     raise "status #{stream.status}" unless stream.status == 200
+    #     Patron::SSEClient.parse(stream) do |event|
+    #       break if event.data == "[DONE]"
+    #       print JSON.parse(event.data).dig("choices", 0, "delta", "content")
+    #     end
+    #   end
+    #
+    # @param stream [Patron::ResponseStream, IO, #readpartial] where the bytes come from
+    # @param last_event_id [String, nil] the ID events carry until the stream sends one
+    # @yieldparam event [Patron::SSEClient::Event]
+    # @return [String, nil] the ID of the last event
+    # @raise [InvalidEncoding] when an event is not valid UTF-8
+    def self.parse(stream, last_event_id: nil, &block)
+      raise ArgumentError, "Patron::SSEClient.parse needs a block" unless block
+      parser = Parser.new(last_event_id: last_event_id)
+      buf = String.new(capacity: CHUNK_SIZE, encoding: Encoding::BINARY)
+      loop do
+        begin
+          stream.readpartial(CHUNK_SIZE, buf)
+        rescue EOFError
+          parser.finish(&block)
+          break
+        end
+        parser.feed(buf, &block)
+      end
+      parser.last_event_id
+    end
+
+    # @return [String, nil] the ID of the last event, sent as Last-Event-ID when reconnecting
+    attr_reader :last_event_id
+
+    # @param url [String] the stream URL, relative to the Session's base_url if it has one
+    # @param headers [Hash] extra request headers
+    # @param idle_timeout [Numeric] seconds of silence after which the stream is reopened; becomes
+    #   the requests' read_timeout. Servers send comment lines to keep a quiet stream alive.
+    # @param retry [Numeric] seconds to wait before reconnecting, until the server sends a `retry:` field
+    # @param max_reconnects [Integer, nil] how many times in a row to reconnect without receiving an
+    #   event in between, nil for no limit
+    # @param last_event_id [String, nil] the ID to resume from
+    # @param session [Patron::Session, nil] the Session to use, for TLS, proxy, authentication,
+    #   cookies or base_url. Only `timeout` and `read_timeout` are set, per request.
+    def initialize(url, headers: {}, idle_timeout: 60, retry: 3, max_reconnects: nil, last_event_id: nil, session: nil)
+      @url = url
+      @headers = headers
+      @idle_timeout = idle_timeout
+      @retry_interval = binding.local_variable_get(:retry).to_f # `retry` is a keyword, so no plain local
+      @max_reconnects = max_reconnects
+      @last_event_id = last_event_id
+      @parser = Parser.new(last_event_id: last_event_id)
+      @session = session || Session.new
+      @closed = false
+      @wakeup = Thread::Queue.new
+    end
+
+    # Opens the stream and yields every event until the block breaks or raises, the server answers
+    # 204, or #close is called. Reconnects after a clean end of the stream, an idle timeout,
+    # Patron::ConnectionFailed and Patron::PartialFileError.
+    #
+    # @yieldparam event [Patron::SSEClient::Event]
+    # @return [nil]
+    # @raise [UnexpectedResponse] for a response that is not an event stream
+    # @raise [ReconnectsExhausted] when `max_reconnects` is exceeded
+    # @raise [InvalidEncoding] when an event is not valid UTF-8
+    def each_event(&block)
+      raise ArgumentError, "Patron::SSEClient#each_event needs a block" unless block
+      @reconnects = 0
+      until @closed
+        begin
+          return if receive_events(&block) == :no_content
+        rescue Patron::Aborted
+          return if @closed
+          raise
+        rescue Patron::TimeoutError, Patron::ConnectionFailed, Patron::PartialFileError
+          nil
+        end
+        break if @closed
+
+        @reconnects += 1
+        if @max_reconnects && @reconnects > @max_reconnects
+          raise ReconnectsExhausted, "Gave up on #{@url} after #{@max_reconnects} reconnects without an event"
+        end
+        @wakeup.pop(timeout: @retry_interval)
+      end
+      nil
+    end
+
+    # Stops #each_event, which then returns. Safe to call from another thread or fiber.
+    #
+    # @return [nil]
+    def close
+      @closed = true
+      @wakeup << :close
+      @session.interrupt
+      nil
+    end
+
+    # @return [Boolean] whether #close has been called
+    def closed? = @closed
+
+    private
+
+    def request_headers
+      headers = { "Accept" => "text/event-stream", "Cache-Control" => "no-cache" }.merge(@headers)
+      headers["Last-Event-ID"] = @last_event_id if @last_event_id
+      headers
+    end
+
+    def receive_events(&block)
+      @session.get_stream(@url, request_headers, timeout: 0, read_timeout: @idle_timeout) do |stream|
+        # A #close that came before this request started has been reset along with the transfer
+        return if @closed
+        return :no_content if stream.status == 204
+        unless stream.status == 200 && stream.content_type == "text/event-stream"
+          raise UnexpectedResponse.new(stream.status, stream.headers, stream.read(BODY_EXCERPT_SIZE) || +"")
+        end
+        parse(stream, &block)
+      end
+      :eof
+    end
+
+    def parse(stream, &block)
+      buf = String.new(capacity: CHUNK_SIZE, encoding: Encoding::BINARY)
+      @parser.reset
+      loop do
+        begin
+          stream.readpartial(CHUNK_SIZE, buf)
+        rescue EOFError
+          @parser.finish { |event| dispatch(event, &block) }
+          break
+        end
+        @parser.feed(buf) { |event| dispatch(event, &block) }
+      ensure
+        # An id: field counts even without data, so this cannot wait for an event
+        @last_event_id = @parser.last_event_id
+        @retry_interval = @parser.retry_interval if @parser.retry_interval
+      end
+    end
+
+    def dispatch(event)
+      @reconnects = 0
+      yield event
+    end
+  end
+end

data/lib/patron/transfer_stats.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Patron
+
+  # The receipt Session#stream returns once its block has ended: the same head readers as
+  # the ResponseStream had, plus what is only known once the body is over. Frozen and
+  # Ractor-shareable.
+  class TransferStats
+    include ResponseHead
+
+    # @return [Integer] body bytes received, as libcurl counts them (CURLINFO_SIZE_DOWNLOAD_T)
+    attr_reader :downloaded_bytes
+
+    # @return [Integer] request body bytes sent (CURLINFO_SIZE_UPLOAD_T)
+    attr_reader :uploaded_bytes
+
+    # @return [Hash{Symbol => Float}] the same transfer marks as Response#timings
+    attr_reader :timings
+
+    # @return [Hash] the trailers that followed a chunked or HTTP/2 body, in the same shape as
+    #   #headers. Empty when there were none, or when the block left before the end of the body.
+    attr_reader :trailers
+
+    # @param url [String] the effective URL after redirects
+    # @param status [Integer] the HTTP status code
+    # @param redirect_count [Integer] how many redirects were followed
+    # @param header_data [String] the raw header lines of every response in the chain
+    # @param downloaded_bytes [Integer]
+    # @param uploaded_bytes [Integer]
+    # @param timings [Hash{Symbol => Float}]
+    # @param complete [Boolean] whether the body was received to its end
+    # @param trailer_data [String] the raw trailer lines
+    # @param default_charset [String, nil] the charset to assume when the Content-Type header names none
+    def initialize(url:, status:, redirect_count:, header_data:, downloaded_bytes:, uploaded_bytes:, timings:,
+                   complete:, trailer_data: "", default_charset: nil)
+      @url = url
+      @status = status
+      @redirect_count = redirect_count
+      @downloaded_bytes = downloaded_bytes
+      @uploaded_bytes = uploaded_bytes
+      @timings = timings
+      @complete = complete
+      parse_head(header_data, default_charset)
+      @trailers = ResponseHead.headers_from_lines(trailer_lines(trailer_data))
+      Ractor.make_shareable(self)
+    end
+
+    # @return [Boolean] whether the body was received to its end. False when the block left
+    #   early, raised, or the transfer failed.
+    def complete? = @complete
+
+    def inspect
+      "#<Patron::TransferStats @status_line='#{@status_line}' complete=#{@complete} downloaded_bytes=#{@downloaded_bytes}>"
+    end
+
+    private
+
+    def trailer_lines(trailer_data)
+      decode_header_data(trailer_data).each_line.map(&:strip).select { |line| line.match?(HeaderParser::HEADER_LINE_START_RE) }
+    end
+  end
+end

data/lib/patron/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Patron
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/patron.rb

@@ -2,6 +2,7 @@
 
 require 'patron/version'
 require 'patron/session'
+require 'patron/sse_client'
 
 module Patron
   # @return [String] the version of the gem

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: patron
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Aeryn Riley Dowling-Toland
 - Julik Tarkhanov
 bindir: bin
 cert_chain: []
-date: 2026-10-29 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies: []
 description: Ruby HTTP client library based on libcurl
 email:
@@ -31,7 +31,11 @@ files:
 - lib/patron/request.rb
 - lib/patron/response.rb
 - lib/patron/response_decoding.rb
+- lib/patron/response_head.rb
+- lib/patron/response_stream.rb
 - lib/patron/session.rb
+- lib/patron/sse_client.rb
+- lib/patron/transfer_stats.rb
 - lib/patron/util.rb
 - lib/patron/version.rb
 homepage: https://github.com/toland/patron