turbopuffer 2.9.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9787f889c45e5fc5892d8a76e508413d80f5af373c6c04ed8a91a87ad5abe0c0
-  data.tar.gz: 400686f51741d20a8dd15c0f58ad8054d6d1b5ed41afe06e8db1849ade2ab5c9
+  metadata.gz: b2a36dd806fc7e21775b4a0edc355e2d22a0414bbf8e9069324514177f082031
+  data.tar.gz: '099d6f2b73a34fe9485a2b36501cc26b4c9a74f4369f69d61b193b423b82e9d2'
 SHA512:
-  metadata.gz: 2e063904070bd100a6bc86eb9dfc0cba61e9b6ae9d5c148390e358f3cd25d2d33be0937910b6da7428c7e8e5cd7aea32de85d92a98827064ef74fa363b7e5e6e
-  data.tar.gz: d8931336b1455bcde03bf1fcbafe73409c5e13a537e71e8f5397b4703b5299757f60d266da9a4806f6889c68aacee47f9da9a2bfc33d1484f419cbbc4ff50df7
+  metadata.gz: 3a2e126a3c4ae82652aebeaa7a58ecf06207780366faa8e913a598bcc49d8c6c8be90d47bfdb9059206ba03be5b8ed2425cca5004673b0914201d8e87ce9c317
+  data.tar.gz: 584446333353eced6da9ebc066231a892d6ef5a40b58d5e5c4bb260b3b4da73a6e57fe33610af6d34bcee40365024f645df5fb1a6d5caaf9f33777b6bd006742

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [2.10.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.9.0...v2.10.0) (2026-10-29)
+
+
+### Features
+
+* openapi: add encryption_context to customer-managed encryption ([1df756b](https://github.com/turbopuffer/turbopuffer-ruby/commit/1df756b4a97d526ced288201f8d7a5193bfd5c8b))
+* Send client-generated request IDs ([#77](https://github.com/turbopuffer/turbopuffer-ruby/issues/77)) ([3812a2f](https://github.com/turbopuffer/turbopuffer-ruby/commit/3812a2fc924254f1c5c8b67a6f8dd6892b02e7aa))
+* spec: split query consistency into strong and eventual variants ([2e12e6c](https://github.com/turbopuffer/turbopuffer-ruby/commit/2e12e6c36b4bb9ba8dcba9ecddfb243d4bda1dd7))
+* tpuf-engine: add max_staleness_seconds to eventual consistency ([e77b67d](https://github.com/turbopuffer/turbopuffer-ruby/commit/e77b67dc350327860e1f2f75702b162d06cb222e))
+
 ## [2.9.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.8.0...v2.9.0) (2026-10-20)
 
 

data/README.md

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

data/lib/turbopuffer/internal/telemetry.rb

@@ -9,16 +9,30 @@ module Turbopuffer
     # header. The server controls how many requests are recorded by advertising a
     # sample rate in the `X-turbopuffer-Client-Telemetry-Sample-Rate` response header.
     #
+    # Each recorded request is sent with an `X-Request-Id` that its record repeats, so the
+    # server can show the client's timings in the same trace as its own.
+    #
     # @api private
     module Telemetry
       ENV_VAR = "TURBOPUFFER_TELEMETRY"
       HEADER = "x-turbopuffer-client-telemetry"
       SAMPLE_RATE_HEADER = "x-turbopuffer-client-telemetry-sample-rate"
+      # Sorted by ASCII value, so that encoded IDs sort like their bytes.
+      REQUEST_ID_ALPHABET = "234567abcdefghijklmnopqrstuvwxyz"
+      # The bytes in a request ID before it's encoded. The first `REQUEST_ID_RANDOM_BYTES` are
+      # random, and the rest hold the time it was generated.
+      REQUEST_ID_BYTES = 18
+      # The request header that carries the IDs of recorded requests.
+      REQUEST_ID_HEADER = "x-request-id"
+      # The prefix of generated request IDs.
+      REQUEST_ID_PREFIX = "tpreq_"
+      # The random bytes at the start of a request ID.
+      REQUEST_ID_RANDOM_BYTES = 12
 
       ENVELOPE_VERSION = 1
 
       # Keeps the header well under the 8 KB per-line limit of common proxies.
-      MAX_RECORDS_PER_HEADER = 20
+      MAX_RECORDS_PER_HEADER = 16
       MAX_BUFFERED_RECORDS = 1000
 
       TRUE_VALUES = %w[1 true yes on].freeze
@@ -124,6 +138,37 @@ module Turbopuffer
         # @return [Float]
         def random = Kernel.rand
 
+        # @api private
+        #
+        # Encodes `bytes` in base32 with `REQUEST_ID_ALPHABET`, in RFC 4648's bit order without
+        # padding.
+        #
+        # @param bytes [String]
+        #
+        # @return [String]
+        def encode_base32(bytes)
+          bytes.unpack1("B*").scan(/.{1,5}/).map { REQUEST_ID_ALPHABET[_1.ljust(5, "0").to_i(2)] }.join
+        end
+
+        # @api private
+        #
+        # Generates the ID of a request that will be recorded. Its format is private to turbopuffer,
+        # which only links IDs in the format it expects: 12 random bytes, then the 48-bit
+        # millisecond time they were generated XORed with the first 6 random bytes, in base32
+        # after a prefix.
+        #
+        # @param now [Time]
+        # @param random [String] overridden by tests
+        #
+        # @return [String]
+        def new_request_id(now, random: SecureRandom.random_bytes(REQUEST_ID_RANDOM_BYTES))
+          millis = (now.to_r * 1000).floor
+          # The low bytes of the big-endian time.
+          time = [millis].pack("Q>").bytes.last(REQUEST_ID_BYTES - REQUEST_ID_RANDOM_BYTES)
+          masked = time.zip(random.bytes).map { _1 ^ _2 }.pack("C*")
+          REQUEST_ID_PREFIX + encode_base32(random + masked)
+        end
+
         # @api private
         #
         # Returns the buffer shared by clients with the same API key and base URL, or nil if
@@ -234,33 +279,48 @@ module Turbopuffer
 
         # @api private
         #
-        # Samples and buffers a record for one request.
+        # Decides whether to record a request that's starting, returning the sample rate it was
+        # recorded at.
+        #
+        # @return [Float, nil]
+        def sample
+          rate = @sample_rate
+          return nil if rate <= 0.0 || (rate < 1.0 && Telemetry.random >= rate)
+          rate
+        end
+
+        # @api private
+        #
+        # Buffers the record of a request sampled at `sample_rate`.
         #
         # @param method [Symbol, String]
         # @param url [URI::Generic, String]
         # @param status [Integer]
         # @param retries [Integer]
         # @param durations [Hash{Symbol=>Integer}] in nanoseconds
+        # @param sample_rate [Float]
         # @param server_total_ms [Numeric, nil]
         # @param error [String, nil]
         # @param reused [Boolean, nil]
+        # @param request_id [String, nil] the `X-Request-Id` the request was sent with, when the
+        #   client generated it
         def record(
           method:,
           url:,
           status:,
           retries:,
           durations:,
+          sample_rate:,
           server_total_ms: nil,
           error: nil,
-          reused: nil
+          reused: nil,
+          request_id: nil
         )
-          rate = @sample_rate
-          return if rate <= 0.0 || (rate < 1.0 && Telemetry.random >= rate)
-
           rec = {route: Telemetry.route_template(method, url), status: status}
           rec[:error] = error unless error.nil?
           rec[:retries] = retries unless retries.zero?
-          rec[:sample_rate] = rate if rate < 1.0
+          rec[:request_id] = request_id unless request_id.nil?
+          rec[:sample_rate] = sample_rate if sample_rate < 1.0
           durations.each do |name, duration|
             # A zero compress duration means the body wasn't compressed.
             next if name == :compress && duration.zero?
@@ -353,6 +413,11 @@ module Turbopuffer
           @info = info
           # Kept for later attempts until one of them may have reached the server.
           @batch = nil
+          # The rate the request was recorded at, or nil if it isn't recorded. Sampled up front, so
+          # that only requests whose records the server will get are sent with request IDs.
+          @sample_rate = buffer.sample
+          # Sent with every attempt, so retries share the request's trace.
+          @request_id = @sample_rate && Telemetry.new_request_id(Time.now)
         end
 
         # @api private
@@ -360,9 +425,15 @@ module Turbopuffer
         # @param attempt [Integer]
         # @param request [Hash{Symbol=>Object}]
         def attempt_begin(attempt, request)
+          headers = request.fetch(:headers)
           # Taken only once a request is about to be sent, so one that fails before then can't lose it.
-          @batch = @buffer.take if attempt.zero?
-          request.fetch(:headers)[HEADER] = @batch.header if @batch
+          if attempt.zero?
+            @batch = @buffer.take
+            # An ID set by the caller is theirs to use, so the request keeps it and isn't linked.
+            @request_id = nil if headers.key?(REQUEST_ID_HEADER)
+          end
+          headers[HEADER] = @batch.header if @batch
+          headers[REQUEST_ID_HEADER] = @request_id if @request_id
         end
 
         # @api private
@@ -388,6 +459,9 @@ module Turbopuffer
             @buffer.restore(@batch)
             @batch = nil
           end
+          return if @sample_rate.nil?
+          # A rate of zero asks clients to stop recording, even requests that were already sampled.
+          return if @buffer.sample_rate <= 0.0
 
           @buffer.record(
             method: @info.method,
@@ -395,9 +469,11 @@ module Turbopuffer
             status: status(result),
             retries: result.retries,
             durations: durations,
+            sample_rate: @sample_rate,
             server_total_ms: server_total_ms(result.parsed),
             error: error_name(result.error_kind),
-            reused: timings.reused
+            reused: timings.reused,
+            request_id: @request_id
           )
         end
 

data/lib/turbopuffer/models/encryption.rb

@@ -25,7 +25,15 @@ module Turbopuffer
         #   @return [Symbol, :"customer-managed"]
         required :mode, const: :"customer-managed"
 
-        # @!method initialize(key_name:, mode: :"customer-managed")
+        # @!attribute encryption_context
+        #   The AWS KMS encryption context to send with every request that uses the key.
+        #   Only supported on AWS, and must be enabled for your organization. Keys may not
+        #   start with `tpuf:` or `aws:`.
+        #
+        #   @return [Hash{Symbol=>String}, nil]
+        optional :encryption_context, Turbopuffer::Internal::Type::HashOf[String]
+
+        # @!method initialize(key_name:, encryption_context: nil, mode: :"customer-managed")
         #   Some parameter documentations has been truncated, see
         #   {Turbopuffer::Models::Encryption::CustomerManaged} for more details.
         #
@@ -33,6 +41,8 @@ module Turbopuffer
         #
         #   @param key_name [String] The identifier of the CMEK key to use for encryption. For GCP, the fully-qualifi
         #
+        #   @param encryption_context [Hash{Symbol=>String}] The AWS KMS encryption context to send with every request that uses the key. Onl
+        #
         #   @param mode [Symbol, :"customer-managed"]
       end
 

data/lib/turbopuffer/models/namespace_explain_query_params.rb

@@ -30,8 +30,8 @@ module Turbopuffer
       # @!attribute consistency
       #   The consistency level for a query.
       #
-      #   @return [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency, nil]
-      optional :consistency, -> { Turbopuffer::NamespaceExplainQueryParams::Consistency }
+      #   @return [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual, nil]
+      optional :consistency, union: -> { Turbopuffer::NamespaceExplainQueryParams::Consistency }
 
       # @!attribute distance_metric
       #   A function used to calculate vector similarity.
@@ -107,7 +107,7 @@ module Turbopuffer
       #
       #   @param compute_attributes [Hash{Symbol=>Object}] Computes additional values on documents returned by a query. Each key is the nam
       #
-      #   @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency] The consistency level for a query.
+      #   @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual] The consistency level for a query.
       #
       #   @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] A function used to calculate vector similarity.
       #
@@ -131,33 +131,59 @@ module Turbopuffer
       #
       #   @param request_options [Turbopuffer::RequestOptions, Hash{Symbol=>Object}]
 
-      class Consistency < Turbopuffer::Internal::Type::BaseModel
-        # @!attribute level
-        #   The query's consistency level.
-        #
-        #   @return [Symbol, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Level, nil]
-        optional :level, enum: -> { Turbopuffer::NamespaceExplainQueryParams::Consistency::Level }
+      # The consistency level for a query.
+      module Consistency
+        extend Turbopuffer::Internal::Type::Union
+
+        discriminator :level
 
-        # @!method initialize(level: nil)
-        #   The consistency level for a query.
-        #
-        #   @param level [Symbol, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Level] The query's consistency level.
+        # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
+        variant :strong, -> { Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong }
 
-        # The query's consistency level.
-        #
-        # @see Turbopuffer::Models::NamespaceExplainQueryParams::Consistency#level
-        module Level
-          extend Turbopuffer::Internal::Type::Enum
+        # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
+        variant :eventual, -> { Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual }
 
-          # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
-          STRONG = :strong
+        class Strong < Turbopuffer::Internal::Type::BaseModel
+          # @!attribute level
+          #
+          #   @return [Symbol, :strong]
+          required :level, const: :strong
 
-          # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
-          EVENTUAL = :eventual
+          # @!method initialize(level: :strong)
+          #   Strong consistency. Requires a round-trip to object storage to fetch the latest
+          #   writes.
+          #
+          #   @param level [Symbol, :strong]
+        end
 
-          # @!method self.values
-          #   @return [Array<Symbol>]
+        class Eventual < Turbopuffer::Internal::Type::BaseModel
+          # @!attribute level
+          #
+          #   @return [Symbol, :eventual]
+          required :level, const: :eventual
+
+          # @!attribute max_staleness_seconds
+          #   How long the query may reuse the node's cached view of the namespace before
+          #   refreshing it from object storage. Defaults to 60.
+          #
+          #   @return [Integer, nil]
+          optional :max_staleness_seconds, Integer
+
+          # @!method initialize(max_staleness_seconds: nil, level: :eventual)
+          #   Some parameter documentations has been truncated, see
+          #   {Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual} for
+          #   more details.
+          #
+          #   Eventual consistency. Does not require a round-trip to object storage, but may
+          #   not see the latest writes.
+          #
+          #   @param max_staleness_seconds [Integer] How long the query may reuse the node's cached view of the namespace before refr
+          #
+          #   @param level [Symbol, :eventual]
         end
+
+        # @!method self.variants
+        #   @return [Array(Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual)]
       end
 
       # Limits the documents returned by a query.

data/lib/turbopuffer/models/namespace_multi_query_params.rb

@@ -21,8 +21,8 @@ module Turbopuffer
       # @!attribute consistency
       #   The consistency level for a query.
       #
-      #   @return [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency, nil]
-      optional :consistency, -> { Turbopuffer::NamespaceMultiQueryParams::Consistency }
+      #   @return [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual, nil]
+      optional :consistency, union: -> { Turbopuffer::NamespaceMultiQueryParams::Consistency }
 
       # @!attribute limit
       #   Limits the total number of reranked documents returned.
@@ -57,7 +57,7 @@ module Turbopuffer
       #
       #   @param namespace [String]
       #
-      #   @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency] The consistency level for a query.
+      #   @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual] The consistency level for a query.
       #
       #   @param limit [Integer, Turbopuffer::Models::RerankLimit] Limits the total number of reranked documents returned.
       #
@@ -188,33 +188,59 @@ module Turbopuffer
         end
       end
 
-      class Consistency < Turbopuffer::Internal::Type::BaseModel
-        # @!attribute level
-        #   The query's consistency level.
-        #
-        #   @return [Symbol, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Level, nil]
-        optional :level, enum: -> { Turbopuffer::NamespaceMultiQueryParams::Consistency::Level }
+      # The consistency level for a query.
+      module Consistency
+        extend Turbopuffer::Internal::Type::Union
 
-        # @!method initialize(level: nil)
-        #   The consistency level for a query.
-        #
-        #   @param level [Symbol, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Level] The query's consistency level.
+        discriminator :level
 
-        # The query's consistency level.
-        #
-        # @see Turbopuffer::Models::NamespaceMultiQueryParams::Consistency#level
-        module Level
-          extend Turbopuffer::Internal::Type::Enum
+        # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
+        variant :strong, -> { Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong }
 
-          # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
-          STRONG = :strong
+        # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
+        variant :eventual, -> { Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual }
 
-          # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
-          EVENTUAL = :eventual
+        class Strong < Turbopuffer::Internal::Type::BaseModel
+          # @!attribute level
+          #
+          #   @return [Symbol, :strong]
+          required :level, const: :strong
 
-          # @!method self.values
-          #   @return [Array<Symbol>]
+          # @!method initialize(level: :strong)
+          #   Strong consistency. Requires a round-trip to object storage to fetch the latest
+          #   writes.
+          #
+          #   @param level [Symbol, :strong]
         end
+
+        class Eventual < Turbopuffer::Internal::Type::BaseModel
+          # @!attribute level
+          #
+          #   @return [Symbol, :eventual]
+          required :level, const: :eventual
+
+          # @!attribute max_staleness_seconds
+          #   How long the query may reuse the node's cached view of the namespace before
+          #   refreshing it from object storage. Defaults to 60.
+          #
+          #   @return [Integer, nil]
+          optional :max_staleness_seconds, Integer
+
+          # @!method initialize(max_staleness_seconds: nil, level: :eventual)
+          #   Some parameter documentations has been truncated, see
+          #   {Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual} for more
+          #   details.
+          #
+          #   Eventual consistency. Does not require a round-trip to object storage, but may
+          #   not see the latest writes.
+          #
+          #   @param max_staleness_seconds [Integer] How long the query may reuse the node's cached view of the namespace before refr
+          #
+          #   @param level [Symbol, :eventual]
+        end
+
+        # @!method self.variants
+        #   @return [Array(Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual)]
       end
 
       # Limits the total number of reranked documents returned.

data/lib/turbopuffer/models/namespace_query_params.rb

@@ -30,8 +30,8 @@ module Turbopuffer
       # @!attribute consistency
       #   The consistency level for a query.
       #
-      #   @return [Turbopuffer::Models::NamespaceQueryParams::Consistency, nil]
-      optional :consistency, -> { Turbopuffer::NamespaceQueryParams::Consistency }
+      #   @return [Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual, nil]
+      optional :consistency, union: -> { Turbopuffer::NamespaceQueryParams::Consistency }
 
       # @!attribute distance_metric
       #   A function used to calculate vector similarity.
@@ -113,7 +113,7 @@ module Turbopuffer
       #
       #   @param compute_attributes [Hash{Symbol=>Object}] Computes additional values on documents returned by a query. Each key is the nam
       #
-      #   @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency] The consistency level for a query.
+      #   @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual] The consistency level for a query.
       #
       #   @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] A function used to calculate vector similarity.
       #
@@ -139,33 +139,59 @@ module Turbopuffer
       #
       #   @param request_options [Turbopuffer::RequestOptions, Hash{Symbol=>Object}]
 
-      class Consistency < Turbopuffer::Internal::Type::BaseModel
-        # @!attribute level
-        #   The query's consistency level.
-        #
-        #   @return [Symbol, Turbopuffer::Models::NamespaceQueryParams::Consistency::Level, nil]
-        optional :level, enum: -> { Turbopuffer::NamespaceQueryParams::Consistency::Level }
+      # The consistency level for a query.
+      module Consistency
+        extend Turbopuffer::Internal::Type::Union
+
+        discriminator :level
 
-        # @!method initialize(level: nil)
-        #   The consistency level for a query.
-        #
-        #   @param level [Symbol, Turbopuffer::Models::NamespaceQueryParams::Consistency::Level] The query's consistency level.
+        # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
+        variant :strong, -> { Turbopuffer::NamespaceQueryParams::Consistency::Strong }
 
-        # The query's consistency level.
-        #
-        # @see Turbopuffer::Models::NamespaceQueryParams::Consistency#level
-        module Level
-          extend Turbopuffer::Internal::Type::Enum
+        # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
+        variant :eventual, -> { Turbopuffer::NamespaceQueryParams::Consistency::Eventual }
 
-          # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
-          STRONG = :strong
+        class Strong < Turbopuffer::Internal::Type::BaseModel
+          # @!attribute level
+          #
+          #   @return [Symbol, :strong]
+          required :level, const: :strong
 
-          # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
-          EVENTUAL = :eventual
+          # @!method initialize(level: :strong)
+          #   Strong consistency. Requires a round-trip to object storage to fetch the latest
+          #   writes.
+          #
+          #   @param level [Symbol, :strong]
+        end
 
-          # @!method self.values
-          #   @return [Array<Symbol>]
+        class Eventual < Turbopuffer::Internal::Type::BaseModel
+          # @!attribute level
+          #
+          #   @return [Symbol, :eventual]
+          required :level, const: :eventual
+
+          # @!attribute max_staleness_seconds
+          #   How long the query may reuse the node's cached view of the namespace before
+          #   refreshing it from object storage. Defaults to 60.
+          #
+          #   @return [Integer, nil]
+          optional :max_staleness_seconds, Integer
+
+          # @!method initialize(max_staleness_seconds: nil, level: :eventual)
+          #   Some parameter documentations has been truncated, see
+          #   {Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual} for more
+          #   details.
+          #
+          #   Eventual consistency. Does not require a round-trip to object storage, but may
+          #   not see the latest writes.
+          #
+          #   @param max_staleness_seconds [Integer] How long the query may reuse the node's cached view of the namespace before refr
+          #
+          #   @param level [Symbol, :eventual]
         end
+
+        # @!method self.variants
+        #   @return [Array(Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual)]
       end
 
       # Limits the documents returned by a query.

data/lib/turbopuffer/resources/namespaces.rb

@@ -106,7 +106,7 @@ module Turbopuffer
       #
       # @param compute_attributes [Hash{Symbol=>Object}] Body param: Computes additional values on documents returned by a query. Each ke
       #
-      # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency] Body param: The consistency level for a query.
+      # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
       #
       # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] Body param: A function used to calculate vector similarity.
       #
@@ -209,7 +209,7 @@ module Turbopuffer
       #
       # @param namespace [String] Path param: The name of the namespace.
       #
-      # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency] Body param: The consistency level for a query.
+      # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
       #
       # @param limit [Integer, Turbopuffer::Models::RerankLimit] Body param: Limits the total number of reranked documents returned.
       #
@@ -279,7 +279,7 @@ module Turbopuffer
       #
       # @param compute_attributes [Hash{Symbol=>Object}] Body param: Computes additional values on documents returned by a query. Each ke
       #
-      # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency] Body param: The consistency level for a query.
+      # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
       #
       # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] Body param: A function used to calculate vector similarity.
       #

data/lib/turbopuffer/version.rb

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

data/rbi/turbopuffer/internal/telemetry.rbi

@@ -9,6 +9,16 @@ module Turbopuffer
       ENV_VAR = T.let(T.unsafe(nil), String)
       HEADER = T.let(T.unsafe(nil), String)
       SAMPLE_RATE_HEADER = T.let(T.unsafe(nil), String)
+      # Sorted by ASCII value, so that encoded IDs sort like their bytes.
+      REQUEST_ID_ALPHABET = T.let(T.unsafe(nil), String)
+      # The bytes in a request ID before it's encoded.
+      REQUEST_ID_BYTES = T.let(T.unsafe(nil), Integer)
+      # The request header that carries the IDs of recorded requests.
+      REQUEST_ID_HEADER = T.let(T.unsafe(nil), String)
+      # The prefix of generated request IDs.
+      REQUEST_ID_PREFIX = T.let(T.unsafe(nil), String)
+      # The random bytes at the start of a request ID.
+      REQUEST_ID_RANDOM_BYTES = T.let(T.unsafe(nil), Integer)
 
       ENVELOPE_VERSION = T.let(T.unsafe(nil), Integer)
 
@@ -60,6 +70,24 @@ module Turbopuffer
         def random
         end
 
+        # @api private
+        #
+        # Encodes `bytes` in base32 with `REQUEST_ID_ALPHABET`, in RFC 4648's bit order without
+        # padding.
+        sig { params(bytes: String).returns(String) }
+        def encode_base32(bytes)
+        end
+
+        # @api private
+        #
+        # Generates the ID of a request that will be recorded. Its format is private to turbopuffer.
+        sig { params(now: Time, random: String).returns(String) }
+        def new_request_id(
+          now,
+          random: SecureRandom.random_bytes(REQUEST_ID_RANDOM_BYTES)
+        )
+        end
+
         # @api private
         #
         # Returns the buffer shared by clients with the same API key and base URL, or nil if
@@ -129,7 +157,15 @@ module Turbopuffer
 
         # @api private
         #
-        # Samples and buffers a record for one request.
+        # Decides whether to record a request that's starting, returning the sample rate it was
+        # recorded at.
+        sig { returns(T.nilable(Float)) }
+        def sample
+        end
+
+        # @api private
+        #
+        # Buffers the record of a request sampled at `sample_rate`.
         sig do
           params(
             method: T.any(Symbol, String),
@@ -137,9 +173,11 @@ module Turbopuffer
             status: Integer,
             retries: Integer,
             durations: T::Hash[Symbol, Integer],
+            sample_rate: Float,
             server_total_ms: T.nilable(Numeric),
             error: T.nilable(String),
-            reused: T.nilable(T::Boolean)
+            reused: T.nilable(T::Boolean),
+            request_id: T.nilable(String)
           ).void
         end
         def record(
@@ -148,9 +186,11 @@ module Turbopuffer
           status:,
           retries:,
           durations:,
+          sample_rate:,
           server_total_ms: nil,
           error: nil,
-          reused: nil
+          reused: nil,
+          request_id: nil
         )
         end