turbopuffer 2.8.0 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +9 -0
  3. data/README.md +15 -1
  4. data/lib/turbopuffer/client.rb +7 -0
  5. data/lib/turbopuffer/internal/respond_async.rb +1 -1
  6. data/lib/turbopuffer/internal/telemetry.rb +462 -0
  7. data/lib/turbopuffer/internal/transport/base_client.rb +50 -21
  8. data/lib/turbopuffer/internal/transport/pooled_net_requester.rb +77 -2
  9. data/lib/turbopuffer/internal/transport/request_observer.rb +377 -0
  10. data/lib/turbopuffer/models/attribute_schema_config.rb +1 -0
  11. data/lib/turbopuffer/models/branch_from_namespace_params.rb +3 -0
  12. data/lib/turbopuffer/models/copy_from_namespace_operation.rb +8 -1
  13. data/lib/turbopuffer/models/copy_from_namespace_operation_result.rb +5 -3
  14. data/lib/turbopuffer/models/copy_from_namespace_params.rb +3 -0
  15. data/lib/turbopuffer/models/full_text_search.rb +1 -0
  16. data/lib/turbopuffer/models/id.rb +1 -1
  17. data/lib/turbopuffer/models/namespace_hint_cache_warm_response.rb +2 -1
  18. data/lib/turbopuffer/models/namespace_metadata.rb +10 -1
  19. data/lib/turbopuffer/models/namespace_metadata_patch.rb +1 -0
  20. data/lib/turbopuffer/models/namespace_multi_query_params.rb +1 -0
  21. data/lib/turbopuffer/models/namespace_multi_query_response.rb +19 -2
  22. data/lib/turbopuffer/models/namespace_query_response.rb +10 -2
  23. data/lib/turbopuffer/models/namespace_recall_response.rb +5 -0
  24. data/lib/turbopuffer/models/namespace_start_copy_from_response.rb +2 -0
  25. data/lib/turbopuffer/models/namespace_write_params.rb +3 -3
  26. data/lib/turbopuffer/models/operation_error.rb +2 -0
  27. data/lib/turbopuffer/models/write_result.rb +1 -1
  28. data/lib/turbopuffer/resources/namespaces.rb +1 -1
  29. data/lib/turbopuffer/version.rb +1 -1
  30. data/lib/turbopuffer.rb +2 -0
  31. data/rbi/turbopuffer/client.rbi +5 -0
  32. data/rbi/turbopuffer/internal/telemetry.rbi +275 -0
  33. data/rbi/turbopuffer/internal/transport/base_client.rbi +13 -2
  34. data/rbi/turbopuffer/internal/transport/pooled_net_requester.rbi +47 -1
  35. data/rbi/turbopuffer/internal/transport/request_observer.rbi +340 -0
  36. data/rbi/turbopuffer/models/branch_from_namespace_params.rbi +1 -0
  37. data/rbi/turbopuffer/models/copy_from_namespace_operation.rbi +4 -0
  38. data/rbi/turbopuffer/models/copy_from_namespace_operation_result.rbi +8 -3
  39. data/rbi/turbopuffer/models/copy_from_namespace_params.rbi +1 -0
  40. data/rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi +2 -0
  41. data/rbi/turbopuffer/models/namespace_metadata.rbi +5 -0
  42. data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
  43. data/rbi/turbopuffer/models/namespace_query_response.rbi +8 -1
  44. data/rbi/turbopuffer/models/namespace_recall_response.rbi +4 -0
  45. data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi +1 -0
  46. data/rbi/turbopuffer/models/namespace_write_params.rbi +3 -3
  47. data/rbi/turbopuffer/models/operation_error.rbi +1 -0
  48. data/rbi/turbopuffer/models/write_result.rbi +1 -1
  49. data/rbi/turbopuffer/resources/namespaces.rbi +2 -1
  50. data/sig/turbopuffer/client.rbs +1 -0
  51. data/sig/turbopuffer/internal/telemetry.rbs +129 -0
  52. data/sig/turbopuffer/internal/transport/base_client.rbs +5 -1
  53. data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs +15 -1
  54. data/sig/turbopuffer/internal/transport/request_observer.rbs +153 -0
  55. metadata +8 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a9ea10142f4e8c684cf18f5657f30b47bfa9f6e3abdae0473e720ac63ac82e7a
4
- data.tar.gz: cb8e5b3806055824b02f4d135c6687c93a9b9f4cc22f239c1dc03c5e22782b04
3
+ metadata.gz: 9787f889c45e5fc5892d8a76e508413d80f5af373c6c04ed8a91a87ad5abe0c0
4
+ data.tar.gz: 400686f51741d20a8dd15c0f58ad8054d6d1b5ed41afe06e8db1849ade2ab5c9
5
5
  SHA512:
6
- metadata.gz: 04f840dc0dd750b28b63a46e1b363abb277508d3a25dbc216d5095fd89a408b2093b944a7421f044bab242b2457298ccfe5471c9ea42df2975a5b7b310ad9856
7
- data.tar.gz: b8b809ed55838462235995bb2ab0f7e20aafdf96273e3dfff1e71086bc777bbe0d5d5583c1e6e858b97bc3f064b4d1682c60cc48cbe28232436c5d8598659c0b
6
+ metadata.gz: 2e063904070bd100a6bc86eb9dfc0cba61e9b6ae9d5c148390e358f3cd25d2d33be0937910b6da7428c7e8e5cd7aea32de85d92a98827064ef74fa363b7e5e6e
7
+ data.tar.gz: d8931336b1455bcde03bf1fcbafe73409c5e13a537e71e8f5397b4703b5299757f60d266da9a4806f6889c68aacee47f9da9a2bfc33d1484f419cbbc4ff50df7
data/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.9.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.8.0...v2.9.0) (2026-10-20)
4
+
5
+
6
+ ### Features
7
+
8
+ * Bound document IDs to 0 so they become `u64` in Rust ([b5b3f8d](https://github.com/turbopuffer/turbopuffer-ruby/commit/b5b3f8d237cd8a488634cbc83a2bc67e0318e7da))
9
+ * Listen via request observer and send client telemetry ([ac17f80](https://github.com/turbopuffer/turbopuffer-ruby/commit/ac17f80196e631bd114270ba75b2b34a244f8e5f))
10
+ * OpenAPI: Add missing descriptions to prettify docblocks in output SDKs ([712aef9](https://github.com/turbopuffer/turbopuffer-ruby/commit/712aef9d7f7b21807a7aef09509a158a6317611c))
11
+
3
12
  ## [2.8.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.7.0...v2.8.0) (2026-10-13)
4
13
 
5
14
 
data/README.md CHANGED
@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
17
17
  <!-- x-release-please-start-version -->
18
18
 
19
19
  ```ruby
20
- gem "turbopuffer", "~> 2.8.0"
20
+ gem "turbopuffer", "~> 2.9.0"
21
21
  ```
22
22
 
23
23
  <!-- x-release-please-end -->
@@ -173,6 +173,20 @@ turbopuffer = Turbopuffer::Client.new(
173
173
  turbopuffer.namespaces(prefix: "foo", request_options: {compression: true})
174
174
  ```
175
175
 
176
+ ### Client telemetry
177
+
178
+ The client can report its own request timings to turbopuffer to help diagnose latency between your application and the API. Telemetry is disabled by default. To enable it, set the `TURBOPUFFER_TELEMETRY` environment variable to `1`, or pass `telemetry: true`:
179
+
180
+ ```ruby
181
+ turbopuffer = Turbopuffer::Client.new(
182
+ telemetry: true
183
+ )
184
+ ```
185
+
186
+ An explicit `telemetry: false` disables telemetry even when the environment variable is set.
187
+
188
+ When enabled, timings for completed requests are attached to subsequent requests in the `X-turbopuffer-Client-Telemetry` header, so no additional requests are made. Each record contains the request's method and path with the namespace name removed, its status code, retry count, whether it reused an existing connection, and client-side durations (serialization, waiting for a free connection, connecting, sending, waiting for the response, reading the response body, and deserialization). Request and response bodies and API keys are never included. turbopuffer may ask the client to record only a sample of requests.
189
+
176
190
  ## Advanced concepts
177
191
 
178
192
  ### BaseModel
@@ -85,6 +85,9 @@ module Turbopuffer
85
85
  #
86
86
  # @param compression [Boolean] Whether to request compressed responses. Defaults to false.
87
87
  #
88
+ # @param telemetry [Boolean, nil] Whether to report client-side request timings to turbopuffer on
89
+ # subsequent requests. Defaults to `ENV["TURBOPUFFER_TELEMETRY"]`, and is off when that's unset.
90
+ #
88
91
  # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
89
92
  #
90
93
  # @param timeout [Float]
@@ -98,6 +101,7 @@ module Turbopuffer
98
101
  default_namespace: nil,
99
102
  base_url: ENV["TURBOPUFFER_BASE_URL"],
100
103
  compression: false,
104
+ telemetry: nil,
101
105
  max_retries: self.class::DEFAULT_MAX_RETRIES,
102
106
  timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
103
107
  initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
@@ -143,6 +147,9 @@ module Turbopuffer
143
147
  max_retry_delay: max_retry_delay,
144
148
  headers: headers
145
149
  )
150
+
151
+ buffer = Turbopuffer::Internal::Telemetry.buffer_for(telemetry, @api_key, @base_url.to_s)
152
+ self.request_observer = Turbopuffer::Internal::Telemetry::Observer.new(buffer) if buffer
146
153
  end
147
154
  end
148
155
  end
@@ -157,7 +157,7 @@ module Turbopuffer
157
157
  sleep(timeout.sleep_duration)
158
158
  nil
159
159
  in {status: "finished", result: {success: success}}
160
- response = Net::HTTPOK.new("1.1", 200, "OK")
160
+ response = Net::HTTPOK.new("1.1", "200", "OK")
161
161
  response["content-type"] = "application/json"
162
162
  [200, response, [JSON.generate(success)]]
163
163
  in {status: "finished", result: {error: {status_code: Integer => err_status, **rest}}}
@@ -0,0 +1,462 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Turbopuffer
4
+ module Internal
5
+ # Client telemetry reported to turbopuffer on subsequent requests.
6
+ #
7
+ # When enabled, the client buffers a small timing record for each request and
8
+ # attaches buffered records to a later request in the `X-turbopuffer-Client-Telemetry`
9
+ # header. The server controls how many requests are recorded by advertising a
10
+ # sample rate in the `X-turbopuffer-Client-Telemetry-Sample-Rate` response header.
11
+ #
12
+ # @api private
13
+ module Telemetry
14
+ ENV_VAR = "TURBOPUFFER_TELEMETRY"
15
+ HEADER = "x-turbopuffer-client-telemetry"
16
+ SAMPLE_RATE_HEADER = "x-turbopuffer-client-telemetry-sample-rate"
17
+
18
+ ENVELOPE_VERSION = 1
19
+
20
+ # Keeps the header well under the 8 KB per-line limit of common proxies.
21
+ MAX_RECORDS_PER_HEADER = 20
22
+ MAX_BUFFERED_RECORDS = 1000
23
+
24
+ TRUE_VALUES = %w[1 true yes on].freeze
25
+ FALSE_VALUES = ["", "0", "false", "no", "off"].freeze
26
+
27
+ NAMESPACE_RE = %r{\A(/v\d+/namespaces/)[^/?]+}
28
+ OPERATION_RE = %r{(/operations/)[^/?]+}
29
+ SCHEME_AND_HOST_RE = %r{\A[a-z][a-z\d+\-.]*://[^/?#]*}i
30
+
31
+ class << self
32
+ # @api private
33
+ #
34
+ # Resolves whether telemetry is enabled, preferring an explicit value over the environment.
35
+ #
36
+ # @param value [Boolean, nil]
37
+ #
38
+ # @return [Boolean]
39
+ def resolve_enabled(value)
40
+ return value unless value.nil?
41
+
42
+ raw = ENV.fetch(ENV_VAR, "")
43
+ env = raw.strip.downcase
44
+ return true if TRUE_VALUES.include?(env)
45
+ unless FALSE_VALUES.include?(env)
46
+ warn("Turbopuffer: ignoring invalid #{ENV_VAR}=#{raw.inspect}, expected 1 or 0")
47
+ end
48
+ false
49
+ end
50
+
51
+ # @api private
52
+ #
53
+ # Returns the method and path of a request with identifiers like the namespace replaced.
54
+ #
55
+ # @param method [Symbol, String]
56
+ # @param url [URI::Generic, String]
57
+ #
58
+ # @return [String]
59
+ def route_template(method, url)
60
+ path = url.to_s.sub(SCHEME_AND_HOST_RE, "")
61
+ path = path.sub(NAMESPACE_RE, '\1{ns}').gsub(OPERATION_RE, '\1{token}')
62
+ "#{method.to_s.upcase} #{path}"
63
+ end
64
+
65
+ # @api private
66
+ #
67
+ # Returns the duration in nanoseconds of each client-side phase of an attempt ending at
68
+ # `end_at`. Phases that weren't observed are left out.
69
+ #
70
+ # @param timings [Turbopuffer::Internal::Transport::RequestObserver::Timings]
71
+ # @param end_at [Integer]
72
+ #
73
+ # @return [Hash{Symbol=>Integer}]
74
+ def compute_durations(timings, end_at)
75
+ durations = {}
76
+ return durations if timings.attempt_begin.nil?
77
+ durations[:total] = end_at - timings.attempt_begin
78
+
79
+ if timings.serialize_begin && timings.serialize_end
80
+ durations[:serialize] = timings.serialize_end - timings.serialize_begin
81
+ end
82
+
83
+ # Set by transports that compress request bodies.
84
+ compress_begin, compress_end = timings.extra.values_at(:compress_begin, :compress_end)
85
+ if compress_begin && compress_end
86
+ durations[:compress] = compress_end - compress_begin
87
+ end
88
+
89
+ # Waiting for a free connection, until connecting a new one or sending on a reused one.
90
+ pool_begin = compress_end || timings.request_ready
91
+ connection_ready = timings.connect_begin || timings.send_begin
92
+ if pool_begin && connection_ready
93
+ durations[:pool] = [connection_ready - pool_begin, 0].max
94
+ end
95
+
96
+ if timings.connect_begin && timings.connect_end
97
+ durations[:connect] = timings.connect_end - timings.connect_begin
98
+ end
99
+
100
+ if timings.send_begin && timings.send_end
101
+ durations[:send] = timings.send_end - timings.send_begin
102
+ end
103
+
104
+ # Covers the network round trip and the server.
105
+ if timings.send_end && timings.response_headers
106
+ durations[:wait] = [timings.response_headers - timings.send_end, 0].max
107
+ end
108
+
109
+ if timings.body_end && timings.response_headers
110
+ durations[:body_read] = timings.body_end - timings.response_headers
111
+ end
112
+
113
+ if timings.deserialize_begin && timings.deserialize_end
114
+ durations[:deserialize] = timings.deserialize_end - timings.deserialize_begin
115
+ end
116
+
117
+ durations
118
+ end
119
+
120
+ # @api private
121
+ #
122
+ # Indirection so tests can control sampling.
123
+ #
124
+ # @return [Float]
125
+ def random = Kernel.rand
126
+
127
+ # @api private
128
+ #
129
+ # Returns the buffer shared by clients with the same API key and base URL, or nil if
130
+ # telemetry is disabled. Sharing lets records ride on any client's requests, but never
131
+ # to another org or region.
132
+ #
133
+ # @param enabled [Boolean, nil]
134
+ # @param api_key [String]
135
+ # @param base_url [String]
136
+ #
137
+ # @return [Turbopuffer::Internal::Telemetry::Buffer, nil]
138
+ def buffer_for(enabled, api_key, base_url)
139
+ return nil unless resolve_enabled(enabled)
140
+
141
+ key = [api_key, base_url]
142
+ @lock.synchronize do
143
+ holder = @shared[key]
144
+ buffer = holder && @buffers[holder]
145
+ unless buffer
146
+ # Drops the keys of freed buffers.
147
+ @shared.delete_if { !@buffers.key?(_2) }
148
+ buffer = Buffer.new
149
+ holder = Object.new
150
+ @buffers[holder] = buffer
151
+ @shared[key] = holder
152
+ install_fork_hook
153
+ end
154
+ buffer
155
+ end
156
+ end
157
+
158
+ # @api private
159
+ def after_fork_in_child
160
+ @lock = Mutex.new
161
+ @buffers.each_value(&:reset_after_fork)
162
+ end
163
+
164
+ private
165
+
166
+ def install_fork_hook
167
+ return if @fork_hook_installed
168
+ Process.singleton_class.prepend(ForkHook)
169
+ @fork_hook_installed = true
170
+ end
171
+ end
172
+
173
+ # @api private
174
+ #
175
+ # Records taken from a buffer, encoded as a header value.
176
+ class Batch
177
+ # @return [Array<Array(Integer, Hash{Symbol=>Object})>]
178
+ attr_reader :records
179
+
180
+ # @return [Integer]
181
+ attr_reader :dropped
182
+
183
+ # @return [String]
184
+ attr_reader :header
185
+
186
+ # @api private
187
+ #
188
+ # @param records [Array<Array(Integer, Hash{Symbol=>Object})>]
189
+ # @param dropped [Integer]
190
+ def initialize(records, dropped)
191
+ @records = records
192
+ @dropped = dropped
193
+
194
+ now = Transport::RequestObserver.now
195
+ envelope = {
196
+ version: ENVELOPE_VERSION,
197
+ records: records.map do |recorded_at, rec|
198
+ {**rec, age_ms: ((now - recorded_at) / 1_000_000.0).round}
199
+ end
200
+ }
201
+ envelope[:dropped] = dropped if dropped.positive?
202
+ @header = JSON.generate(envelope)
203
+ end
204
+ end
205
+
206
+ # @api private
207
+ #
208
+ # Buffers per-request telemetry records until a later request can carry them.
209
+ class Buffer
210
+ # @return [Float]
211
+ attr_reader :sample_rate
212
+
213
+ # @api private
214
+ def initialize
215
+ @lock = Mutex.new
216
+ @records = []
217
+ @dropped = 0
218
+ # Used until the server advertises a rate.
219
+ @sample_rate = 1.0
220
+ end
221
+
222
+ # @api private
223
+ #
224
+ # Adopts the sample rate advertised by the server, ignoring invalid values.
225
+ #
226
+ # @param response [Net::HTTPResponse]
227
+ def observe_response(response)
228
+ value = response[SAMPLE_RATE_HEADER]
229
+ return if value.nil?
230
+
231
+ rate = Float(value, exception: false)
232
+ @sample_rate = rate if rate&.between?(0.0, 1.0)
233
+ end
234
+
235
+ # @api private
236
+ #
237
+ # Samples and buffers a record for one request.
238
+ #
239
+ # @param method [Symbol, String]
240
+ # @param url [URI::Generic, String]
241
+ # @param status [Integer]
242
+ # @param retries [Integer]
243
+ # @param durations [Hash{Symbol=>Integer}] in nanoseconds
244
+ # @param server_total_ms [Numeric, nil]
245
+ # @param error [String, nil]
246
+ # @param reused [Boolean, nil]
247
+ def record(
248
+ method:,
249
+ url:,
250
+ status:,
251
+ retries:,
252
+ durations:,
253
+ server_total_ms: nil,
254
+ error: nil,
255
+ reused: nil
256
+ )
257
+ rate = @sample_rate
258
+ return if rate <= 0.0 || (rate < 1.0 && Telemetry.random >= rate)
259
+
260
+ rec = {route: Telemetry.route_template(method, url), status: status}
261
+ rec[:error] = error unless error.nil?
262
+ rec[:retries] = retries unless retries.zero?
263
+ rec[:sample_rate] = rate if rate < 1.0
264
+ durations.each do |name, duration|
265
+ # A zero compress duration means the body wasn't compressed.
266
+ next if name == :compress && duration.zero?
267
+ rec[:"#{name}_us"] = duration / 1000
268
+ end
269
+ rec[:server_total_us] = (server_total_ms * 1000).round unless server_total_ms.nil?
270
+ rec[:reused] = reused unless reused.nil?
271
+
272
+ @lock.synchronize do
273
+ if @records.length >= MAX_BUFFERED_RECORDS
274
+ @records.shift
275
+ @dropped += 1
276
+ end
277
+ @records << [Transport::RequestObserver.now, rec]
278
+ end
279
+ end
280
+
281
+ # @api private
282
+ #
283
+ # Removes up to `MAX_RECORDS_PER_HEADER` of the oldest records.
284
+ #
285
+ # @return [Turbopuffer::Internal::Telemetry::Batch, nil]
286
+ def take
287
+ records, dropped = @lock.synchronize do
288
+ return nil if @records.empty?
289
+ taken = @records.shift(MAX_RECORDS_PER_HEADER)
290
+ dropped = @dropped
291
+ @dropped = 0
292
+ [taken, dropped]
293
+ end
294
+ Batch.new(records, dropped)
295
+ end
296
+
297
+ # @api private
298
+ #
299
+ # Returns a batch that never reached the server to the front of the buffer.
300
+ #
301
+ # @param batch [Turbopuffer::Internal::Telemetry::Batch]
302
+ def restore(batch)
303
+ @lock.synchronize do
304
+ room = [MAX_BUFFERED_RECORDS - @records.length, 0].max
305
+ # The batch holds the oldest records, so they're the ones to drop when full.
306
+ kept = batch.records.last(room)
307
+ @dropped += batch.dropped + batch.records.length - kept.length
308
+ @records.unshift(*kept)
309
+ end
310
+ end
311
+
312
+ # @api private
313
+ def reset_after_fork
314
+ # Another thread may have held the lock at fork time, and buffered records belong to the parent.
315
+ @lock = Mutex.new
316
+ @records = []
317
+ @dropped = 0
318
+ end
319
+ end
320
+
321
+ # @api private
322
+ #
323
+ # Installs the request observer that records telemetry for a client.
324
+ class Observer < Transport::RequestObserver
325
+ # @return [Turbopuffer::Internal::Telemetry::Buffer]
326
+ attr_reader :buffer
327
+
328
+ # @api private
329
+ #
330
+ # @param buffer [Turbopuffer::Internal::Telemetry::Buffer]
331
+ def initialize(buffer)
332
+ super()
333
+ @buffer = buffer
334
+ end
335
+
336
+ # @api private
337
+ #
338
+ # @param info [Turbopuffer::Internal::Transport::RequestObserver::RequestInfo]
339
+ #
340
+ # @return [Turbopuffer::Internal::Telemetry::Scope]
341
+ def start(info) = Scope.new(@buffer, info)
342
+ end
343
+
344
+ # @api private
345
+ class Scope < Transport::RequestObserver::RequestScope
346
+ # @api private
347
+ #
348
+ # @param buffer [Turbopuffer::Internal::Telemetry::Buffer]
349
+ # @param info [Turbopuffer::Internal::Transport::RequestObserver::RequestInfo]
350
+ def initialize(buffer, info)
351
+ super()
352
+ @buffer = buffer
353
+ @info = info
354
+ # Kept for later attempts until one of them may have reached the server.
355
+ @batch = nil
356
+ end
357
+
358
+ # @api private
359
+ #
360
+ # @param attempt [Integer]
361
+ # @param request [Hash{Symbol=>Object}]
362
+ def attempt_begin(attempt, request)
363
+ # Taken only once a request is about to be sent, so one that fails before then can't lose it.
364
+ @batch = @buffer.take if attempt.zero?
365
+ request.fetch(:headers)[HEADER] = @batch.header if @batch
366
+ end
367
+
368
+ # @api private
369
+ #
370
+ # @param result [Turbopuffer::Internal::Transport::RequestObserver::AttemptResult]
371
+ def attempt_end(result)
372
+ @batch = nil unless result.reached_server == false
373
+ @buffer.observe_response(result.response) if result.response
374
+ end
375
+
376
+ # @api private
377
+ #
378
+ # @param result [Turbopuffer::Internal::Transport::RequestObserver::RequestResult]
379
+ def finish(result)
380
+ timings = result.timings
381
+ durations = Telemetry.compute_durations(
382
+ timings,
383
+ timings.deserialize_end || Transport::RequestObserver.now
384
+ )
385
+
386
+ # A batch that never reached the server goes back for a later request.
387
+ if @batch
388
+ @buffer.restore(@batch)
389
+ @batch = nil
390
+ end
391
+
392
+ @buffer.record(
393
+ method: @info.method,
394
+ url: @info.url,
395
+ status: status(result),
396
+ retries: result.retries,
397
+ durations: durations,
398
+ server_total_ms: server_total_ms(result.parsed),
399
+ error: error_name(result.error_kind),
400
+ reused: timings.reused
401
+ )
402
+ end
403
+
404
+ private
405
+
406
+ # A failed respond-async operation has no response of its own, only the error's status.
407
+ def status(result)
408
+ error = result.error
409
+ return error.status if error.is_a?(Turbopuffer::Errors::APIStatusError) && error.status
410
+ result.response ? result.response.code.to_i : 0
411
+ end
412
+
413
+ def error_name(kind)
414
+ if kind.nil?
415
+ nil
416
+ elsif kind == :canceled || kind == :other
417
+ kind.to_s
418
+ elsif kind.end_with?("timeout")
419
+ "timeout"
420
+ else
421
+ "connect"
422
+ end
423
+ end
424
+
425
+ def server_total_ms(parsed)
426
+ value = field(field(parsed, :performance), :server_total_ms)
427
+ value if value.is_a?(Numeric) && value.finite?
428
+ end
429
+
430
+ def field(value, name)
431
+ case value
432
+ in Turbopuffer::Internal::Type::BaseModel | Hash
433
+ value[name]
434
+ else
435
+ nil
436
+ end
437
+ end
438
+ end
439
+
440
+ # @api private
441
+ #
442
+ # Resets telemetry in forked children.
443
+ module ForkHook
444
+ # @api private
445
+ #
446
+ # @return [Integer]
447
+ def _fork
448
+ pid = super
449
+ Telemetry.after_fork_in_child if pid.zero?
450
+ pid
451
+ end
452
+ end
453
+
454
+ @lock = Mutex.new
455
+ # Maps API key and base URL to a holder, since weak maps compare keys by identity.
456
+ @shared = {}
457
+ # Maps holders to buffers weakly, so a buffer is freed with the last client using it.
458
+ @buffers = ObjectSpace::WeakMap.new
459
+ @fork_hook_installed = false
460
+ end
461
+ end
462
+ end