turbopuffer 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20d0c90e03716bcf7ca9387385505eb4bd4711888f16eb0d3bde30d70ad0829a
-  data.tar.gz: 29b6153b4c7250a63170be4c7b1010933ef7c96e7817fd78de6d4790fed8a481
+  metadata.gz: f5782a65079f1aa648db3dde706b11543e0e35a2c93eb14f32d64c42bdc260e5
+  data.tar.gz: 5878b8bf8b11267e60cf1c6edd2f045e6ae427c0da3c12adec20b239179a693f
 SHA512:
-  metadata.gz: b7243b9b3134d2fa3741ed94b79c5813f4d23a5f106d561865a8a9e1891ac76c7cb0d66088bbb3e2b9f0f1970ed023bffc06a9c98059ac8af9e0b8f544b0249d
-  data.tar.gz: f249a2b3afa1092d5bab4ea3510ee6de24719b8e61fbbcc5975f90e6d6ecbc002298283454f0f1eccf9c313f9f7def328b6f508df894f9a852ae3759d8b6ac66
+  metadata.gz: 4716b1484413ac6c3b33583cccb0138c3068b41d7711e5062d81265dcff09dec7ad1508ca6468e08bbaebb1d0390794aaa71b1e026156841e75d6b228cdd71ba
+  data.tar.gz: a8cdfc20d9779db1e32922c6b23053163da52bf1dbe71f4d1555f95ea64ede5ea95c479d62f2975e70213d21ed7e4d754ab77e6f7266587f2029d2ab64e14542

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.2.0 (2026-06-08)
+
+Full Changelog: [v2.1.0...v2.2.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.1.0...v2.2.0)
+
+### Features
+
+* stainless: update sdks to support case-insensitive fuzzy filter ([d02bb79](https://github.com/turbopuffer/turbopuffer-ruby/commit/d02bb79d809f3b2285020f3aac4a3441ac1e38b2))
+* transparent async polling ([#61](https://github.com/turbopuffer/turbopuffer-ruby/issues/61)) ([d93c499](https://github.com/turbopuffer/turbopuffer-ruby/commit/d93c49924d0df4bb4be9935f2090ce6fa26da18e))
+
 ## 2.1.0 (2026-06-03)
 
 Full Changelog: [v2.1.0-alpha.1...v2.1.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.1.0-alpha.1...v2.1.0)

data/README.md

@@ -26,7 +26,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "turbopuffer", "~> 2.1.0"
+gem "turbopuffer", "~> 2.2.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/turbopuffer/internal/respond_async.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Turbopuffer
+  module Internal
+    # Support for transparent polling of async tpuf APIs.
+    #
+    # Every API request is stamped with `Prefer: respond-async`. If the server
+    # applies the preference (i.e. responds with `202 Accepted` +
+    # `preference-applied: respond-async`) the SDK polls that URL until the
+    # operation finishes and returns the final result as if the API call had
+    # been synchronous.
+    #
+    # @api private
+    module RespondAsync
+      HEADER_PREFER = "prefer"
+      HEADER_PREFERENCE_APPLIED = "preference-applied"
+      HEADER_LOCATION = "location"
+      RESPOND_ASYNC = "respond-async"
+
+      POLL_INTERVAL = 1.0
+      POLL_REQUEST_TIMEOUT = 60.0
+
+      # Timeout tracking for async polling.
+      #
+      # @api private
+      class Timeout
+        # @param timeout [Float]
+        def initialize(timeout)
+          @deadline = Turbopuffer::Internal::Util.monotonic_secs + timeout
+        end
+
+        # @return [Float]
+        def remaining
+          [@deadline - Turbopuffer::Internal::Util.monotonic_secs, 0].max
+        end
+
+        # @return [Float]
+        def poll_timeout
+          [remaining, POLL_REQUEST_TIMEOUT].min
+        end
+
+        # @return [Float]
+        def sleep_duration
+          [remaining, POLL_INTERVAL].min
+        end
+      end
+
+      class << self
+        # @param headers [Hash{String=>String}]
+        #
+        # @return [void]
+        def prepare_headers(headers)
+          headers[HEADER_PREFER] ||= RESPOND_ASYNC
+        end
+
+        # @param client [Turbopuffer::Internal::Transport::BaseClient]
+        # @param request [Hash{Symbol=>Object}] the original built request
+        # @param response [Net::HTTPResponse]
+        # @param stream [Enumerable<String>]
+        #
+        # @return [Array(Integer, Net::HTTPResponse, Enumerable<String>)]
+        def maybe_poll(client, request, response, stream)
+          return [Integer(response.code), response, stream] unless respond_async_applied?(response)
+
+          # Drain the original 202 body so the connection returns to the pool.
+          stream&.each { next }
+
+          orig_url = request.fetch(:url)
+          location = extract_location(orig_url, response)
+
+          timeout = Timeout.new(request.fetch(:timeout))
+
+          loop do
+            result = poll_once(client, orig_url, location, timeout)
+            return result if result
+          end
+        end
+
+        private
+
+        # @param response [Net::HTTPResponse]
+        #
+        # @return [Boolean]
+        def respond_async_applied?(response)
+          return false unless response.code == "202"
+
+          applied = response[HEADER_PREFERENCE_APPLIED].to_s
+          applied.strip.downcase == RESPOND_ASYNC
+        end
+
+        # @param orig_url [URI::Generic]
+        # @param response [Net::HTTPResponse]
+        #
+        # @return [URI::Generic]
+        def extract_location(orig_url, response)
+          raw_location = response[HEADER_LOCATION].to_s.strip
+          if raw_location.empty?
+            raise Turbopuffer::Errors::APIError.new(
+              url: orig_url,
+              message: "Server returned async response without a 'Location' header."
+            )
+          end
+
+          # Normalize so the default port for the scheme is applied.
+          orig = URI(orig_url.to_s)
+
+          # Resolve the Location against the original request URL.
+          begin
+            location = URI.join(orig, raw_location)
+          rescue URI::InvalidURIError
+            raise Turbopuffer::Errors::APIError.new(
+              url: orig_url,
+              message: "malformed 'Location' header: #{raw_location.inspect}"
+            )
+          end
+
+          if [location.scheme, location.host, location.port] !=
+             [orig.scheme, orig.host, orig.port]
+            raise Turbopuffer::Errors::APIError.new(
+              url: orig_url,
+              message: "'Location' origin does not match request origin: #{raw_location.inspect}"
+            )
+          end
+
+          location
+        end
+
+        # @param client [Turbopuffer::Internal::Transport::BaseClient]
+        # @param orig_url [URI::Generic]
+        # @param location [URI::Generic]
+        # @param timeout [Timeout]
+        #
+        # @return [Array(Integer, Net::HTTPResponse, Array<String>), nil]
+        def poll_once(client, orig_url, location, timeout)
+          raise Turbopuffer::Errors::APITimeoutError.new(url: orig_url) if timeout.remaining.zero?
+
+          body =
+            begin
+              client.request(
+                method: :get,
+                path: location.request_uri,
+                model: Turbopuffer::Internal::Type::Unknown,
+                options: {
+                  extra_headers: {HEADER_PREFER => ""},
+                  timeout: timeout.poll_timeout
+                }
+              )
+            rescue JSON::ParserError => e
+              raise Turbopuffer::Errors::APIError.new(
+                url: orig_url,
+                message: "malformed poll response: #{e.message}"
+              )
+            end
+
+          case body
+          in {status: "running"}
+            sleep(timeout.sleep_duration)
+            nil
+          in {status: "finished", result: {success: success}}
+            response = Net::HTTPOK.new("1.1", 200, "OK")
+            response["content-type"] = "application/json"
+            [200, response, [JSON.generate(success)]]
+          in {status: "finished", result: {error: {status_code: Integer => err_status, **rest}}}
+            raise Turbopuffer::Errors::APIStatusError.for(
+              url: orig_url,
+              status: err_status,
+              headers: nil,
+              body: rest[:detail],
+              request: nil,
+              response: nil
+            )
+          else
+            raise Turbopuffer::Errors::APIError.new(
+              url: orig_url,
+              message: "malformed poll response: #{body.inspect}"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/internal/transport/base_client.rb

@@ -309,6 +309,8 @@ module Turbopuffer
             headers["x-stainless-timeout"] = timeout.to_s
           end
 
+          Turbopuffer::Internal::RespondAsync.prepare_headers(headers)
+
           headers.reject! { |_, v| v.to_s.empty? }
 
           body =
@@ -501,12 +503,18 @@ module Turbopuffer
 
           # Don't send the current retry count in the headers if the caller modified the header defaults.
           send_retry_header = request.fetch(:headers)["x-stainless-retry-count"] == "0"
-          status, response, stream = send_request(
+          _, response, stream = send_request(
             request,
             redirect_count: 0,
             retry_count: 0,
             send_retry_header: send_retry_header
           )
+          status, response, stream = Turbopuffer::Internal::RespondAsync.maybe_poll(
+            self,
+            request,
+            response,
+            stream
+          )
 
           headers = Turbopuffer::Internal::Util.normalized_headers(response.each_header.to_h)
           decoded = Turbopuffer::Internal::Util.decode_content(headers, stream: stream)

data/lib/turbopuffer/models/fuzzy_params.rb

@@ -11,13 +11,22 @@ module Turbopuffer
       required :max_edit_distance,
                -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::FuzzyMaxEditDistance] }
 
-      # @!method initialize(max_edit_distance:)
+      # @!attribute case_sensitive
+      #   Whether searching with Fuzzy filter is case-sensitive. Defaults to `true` (i.e.
+      #   case-sensitive).
+      #
+      #   @return [Boolean, nil]
+      optional :case_sensitive, Turbopuffer::Internal::Type::Boolean
+
+      # @!method initialize(max_edit_distance:, case_sensitive: nil)
       #   Some parameter documentations has been truncated, see
       #   {Turbopuffer::Models::FuzzyParams} for more details.
       #
       #   Additional parameters for the Fuzzy filter.
       #
       #   @param max_edit_distance [Array<Turbopuffer::Models::FuzzyMaxEditDistance>] Maximum edit distance allowed at each query length. Queries shorter than the fir
+      #
+      #   @param case_sensitive [Boolean] Whether searching with Fuzzy filter is case-sensitive. Defaults to `true` (i.e.
     end
   end
 end

data/lib/turbopuffer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Turbopuffer
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

data/lib/turbopuffer.rb

@@ -51,6 +51,7 @@ require_relative "turbopuffer/file_part"
 require_relative "turbopuffer/errors"
 require_relative "turbopuffer/internal/transport/base_client"
 require_relative "turbopuffer/internal/transport/pooled_net_requester"
+require_relative "turbopuffer/internal/respond_async"
 require_relative "turbopuffer/client"
 require_relative "turbopuffer/internal/namespace_page"
 require_relative "turbopuffer/models/pinning_config"

data/rbi/turbopuffer/models/fuzzy_params.rbi

@@ -13,22 +13,38 @@ module Turbopuffer
       sig { returns(T::Array[Turbopuffer::FuzzyMaxEditDistance]) }
       attr_accessor :max_edit_distance
 
+      # Whether searching with Fuzzy filter is case-sensitive. Defaults to `true` (i.e.
+      # case-sensitive).
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :case_sensitive
+
+      sig { params(case_sensitive: T::Boolean).void }
+      attr_writer :case_sensitive
+
       # Additional parameters for the Fuzzy filter.
       sig do
         params(
-          max_edit_distance: T::Array[Turbopuffer::FuzzyMaxEditDistance::OrHash]
+          max_edit_distance:
+            T::Array[Turbopuffer::FuzzyMaxEditDistance::OrHash],
+          case_sensitive: T::Boolean
         ).returns(T.attached_class)
       end
       def self.new(
         # Maximum edit distance allowed at each query length. Queries shorter than the
         # first threshold return no matches.
-        max_edit_distance:
+        max_edit_distance:,
+        # Whether searching with Fuzzy filter is case-sensitive. Defaults to `true` (i.e.
+        # case-sensitive).
+        case_sensitive: nil
       )
       end
 
       sig do
         override.returns(
-          { max_edit_distance: T::Array[Turbopuffer::FuzzyMaxEditDistance] }
+          {
+            max_edit_distance: T::Array[Turbopuffer::FuzzyMaxEditDistance],
+            case_sensitive: T::Boolean
+          }
         )
       end
       def to_hash

data/sig/turbopuffer/models/fuzzy_params.rbs

@@ -1,17 +1,26 @@
 module Turbopuffer
   module Models
     type fuzzy_params =
-      { max_edit_distance: ::Array[Turbopuffer::FuzzyMaxEditDistance] }
+      {
+        max_edit_distance: ::Array[Turbopuffer::FuzzyMaxEditDistance],
+        case_sensitive: bool
+      }
 
     class FuzzyParams < Turbopuffer::Internal::Type::BaseModel
       attr_accessor max_edit_distance: ::Array[Turbopuffer::FuzzyMaxEditDistance]
 
+      attr_reader case_sensitive: bool?
+
+      def case_sensitive=: (bool) -> bool
+
       def initialize: (
-        max_edit_distance: ::Array[Turbopuffer::FuzzyMaxEditDistance]
+        max_edit_distance: ::Array[Turbopuffer::FuzzyMaxEditDistance],
+        ?case_sensitive: bool
       ) -> void
 
       def to_hash: -> {
-        max_edit_distance: ::Array[Turbopuffer::FuzzyMaxEditDistance]
+        max_edit_distance: ::Array[Turbopuffer::FuzzyMaxEditDistance],
+        case_sensitive: bool
       }
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turbopuffer
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Turbopuffer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -55,6 +55,7 @@ files:
 - lib/turbopuffer/file_part.rb
 - lib/turbopuffer/internal.rb
 - lib/turbopuffer/internal/namespace_page.rb
+- lib/turbopuffer/internal/respond_async.rb
 - lib/turbopuffer/internal/transport/base_client.rb
 - lib/turbopuffer/internal/transport/pooled_net_requester.rb
 - lib/turbopuffer/internal/type/array_of.rb