turbopuffer 2.8.0 → 2.10.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 (67) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +19 -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 +538 -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/encryption.rb +11 -1
  16. data/lib/turbopuffer/models/full_text_search.rb +1 -0
  17. data/lib/turbopuffer/models/id.rb +1 -1
  18. data/lib/turbopuffer/models/namespace_explain_query_params.rb +50 -24
  19. data/lib/turbopuffer/models/namespace_hint_cache_warm_response.rb +2 -1
  20. data/lib/turbopuffer/models/namespace_metadata.rb +10 -1
  21. data/lib/turbopuffer/models/namespace_metadata_patch.rb +1 -0
  22. data/lib/turbopuffer/models/namespace_multi_query_params.rb +51 -24
  23. data/lib/turbopuffer/models/namespace_multi_query_response.rb +19 -2
  24. data/lib/turbopuffer/models/namespace_query_params.rb +50 -24
  25. data/lib/turbopuffer/models/namespace_query_response.rb +10 -2
  26. data/lib/turbopuffer/models/namespace_recall_response.rb +5 -0
  27. data/lib/turbopuffer/models/namespace_start_copy_from_response.rb +2 -0
  28. data/lib/turbopuffer/models/namespace_write_params.rb +3 -3
  29. data/lib/turbopuffer/models/operation_error.rb +2 -0
  30. data/lib/turbopuffer/models/write_result.rb +1 -1
  31. data/lib/turbopuffer/resources/namespaces.rb +4 -4
  32. data/lib/turbopuffer/version.rb +1 -1
  33. data/lib/turbopuffer.rb +2 -0
  34. data/rbi/turbopuffer/client.rbi +5 -0
  35. data/rbi/turbopuffer/internal/telemetry.rbi +315 -0
  36. data/rbi/turbopuffer/internal/transport/base_client.rbi +13 -2
  37. data/rbi/turbopuffer/internal/transport/pooled_net_requester.rbi +47 -1
  38. data/rbi/turbopuffer/internal/transport/request_observer.rbi +340 -0
  39. data/rbi/turbopuffer/models/branch_from_namespace_params.rbi +1 -0
  40. data/rbi/turbopuffer/models/copy_from_namespace_operation.rbi +4 -0
  41. data/rbi/turbopuffer/models/copy_from_namespace_operation_result.rbi +8 -3
  42. data/rbi/turbopuffer/models/copy_from_namespace_params.rbi +1 -0
  43. data/rbi/turbopuffer/models/encryption.rbi +29 -2
  44. data/rbi/turbopuffer/models/namespace_explain_query_params.rbi +84 -71
  45. data/rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi +2 -0
  46. data/rbi/turbopuffer/models/namespace_metadata.rbi +5 -0
  47. data/rbi/turbopuffer/models/namespace_multi_query_params.rbi +86 -71
  48. data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
  49. data/rbi/turbopuffer/models/namespace_query_params.rbi +88 -71
  50. data/rbi/turbopuffer/models/namespace_query_response.rbi +8 -1
  51. data/rbi/turbopuffer/models/namespace_recall_response.rbi +4 -0
  52. data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi +1 -0
  53. data/rbi/turbopuffer/models/namespace_write_params.rbi +3 -3
  54. data/rbi/turbopuffer/models/operation_error.rbi +1 -0
  55. data/rbi/turbopuffer/models/write_result.rbi +1 -1
  56. data/rbi/turbopuffer/resources/namespaces.rbi +15 -4
  57. data/sig/turbopuffer/client.rbs +1 -0
  58. data/sig/turbopuffer/internal/telemetry.rbs +142 -0
  59. data/sig/turbopuffer/internal/transport/base_client.rbs +5 -1
  60. data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs +15 -1
  61. data/sig/turbopuffer/internal/transport/request_observer.rbs +153 -0
  62. data/sig/turbopuffer/models/encryption.rbs +22 -3
  63. data/sig/turbopuffer/models/namespace_explain_query_params.rbs +30 -28
  64. data/sig/turbopuffer/models/namespace_multi_query_params.rbs +30 -28
  65. data/sig/turbopuffer/models/namespace_query_params.rbs +30 -26
  66. data/sig/turbopuffer/resources/namespaces.rbs +3 -3
  67. metadata +9 -3
@@ -178,6 +178,10 @@ module Turbopuffer
178
178
  # @return [Turbopuffer::Internal::Transport::PooledNetRequester]
179
179
  attr_reader :requester
180
180
 
181
+ # @api private
182
+ # @return [Turbopuffer::Internal::Transport::RequestObserver, nil]
183
+ attr_accessor :request_observer
184
+
181
185
  # @api private
182
186
  #
183
187
  # @param base_url [String]
@@ -213,6 +217,7 @@ module Turbopuffer
213
217
  @max_retries = max_retries
214
218
  @initial_retry_delay = initial_retry_delay
215
219
  @max_retry_delay = max_retry_delay
220
+ @request_observer = nil
216
221
  end
217
222
 
218
223
  # @api private
@@ -389,9 +394,11 @@ module Turbopuffer
389
394
  #
390
395
  # @param send_retry_header [Boolean]
391
396
  #
397
+ # @param observation [Turbopuffer::Internal::Transport::RequestObserver::Observation, nil]
398
+ #
392
399
  # @raise [Turbopuffer::Errors::APIError]
393
400
  # @return [Array(Integer, Net::HTTPResponse, Enumerable<String>)]
394
- def send_request(request, redirect_count:, retry_count:, send_retry_header:)
401
+ def send_request(request, redirect_count:, retry_count:, send_retry_header:, observation: nil)
395
402
  url, headers, max_retries, timeout = request.fetch_values(:url, :headers, :max_retries, :timeout)
396
403
  input = {**request.except(:timeout), deadline: Turbopuffer::Internal::Util.monotonic_secs + timeout}
397
404
 
@@ -399,11 +406,13 @@ module Turbopuffer
399
406
  headers["x-stainless-retry-count"] = retry_count.to_s
400
407
  end
401
408
 
409
+ input = observation.attempt_begin(input, retry_count: retry_count) if observation
402
410
  begin
403
411
  status, response, stream = @requester.execute(input)
404
412
  rescue Turbopuffer::Errors::APIConnectionError => e
405
413
  status = e
406
414
  end
415
+ observation&.attempt_end(status, response)
407
416
  headers = Turbopuffer::Internal::Util.normalized_headers(response&.each_header&.to_h)
408
417
 
409
418
  case status
@@ -422,7 +431,8 @@ module Turbopuffer
422
431
  request,
423
432
  redirect_count: redirect_count + 1,
424
433
  retry_count: retry_count,
425
- send_retry_header: send_retry_header
434
+ send_retry_header: send_retry_header,
435
+ observation: observation
426
436
  )
427
437
  in Turbopuffer::Errors::APIConnectionError if retry_count >= max_retries
428
438
  raise status
@@ -451,7 +461,8 @@ module Turbopuffer
451
461
  request,
452
462
  redirect_count: redirect_count,
453
463
  retry_count: retry_count + 1,
454
- send_retry_header: send_retry_header
464
+ send_retry_header: send_retry_header,
465
+ observation: observation
455
466
  )
456
467
  end
457
468
  end
@@ -501,7 +512,16 @@ module Turbopuffer
501
512
  opts = req[:options].to_h
502
513
  unwrap = req[:unwrap]
503
514
  Turbopuffer::RequestOptions.validate!(opts)
515
+ started_at = Turbopuffer::Internal::Transport::RequestObserver.now if @request_observer
504
516
  request = build_request(req.except(:options), opts)
517
+ if started_at
518
+ observation = Turbopuffer::Internal::Transport::RequestObserver::Observation.start(
519
+ @request_observer,
520
+ request,
521
+ started_at,
522
+ path: Turbopuffer::Internal::Util.interpolate_path(req.fetch(:path))
523
+ )
524
+ end
505
525
  url = request.fetch(:url)
506
526
 
507
527
  # Don't send the current retry count in the headers if the caller modified the header defaults.
@@ -510,7 +530,8 @@ module Turbopuffer
510
530
  request,
511
531
  redirect_count: 0,
512
532
  retry_count: 0,
513
- send_retry_header: send_retry_header
533
+ send_retry_header: send_retry_header,
534
+ observation: observation
514
535
  )
515
536
  status, response, stream = Turbopuffer::Internal::RespondAsync.maybe_poll(
516
537
  self,
@@ -520,24 +541,32 @@ module Turbopuffer
520
541
  )
521
542
 
522
543
  headers = Turbopuffer::Internal::Util.normalized_headers(response.each_header.to_h)
544
+ observation&.deserialize_begin
523
545
  decoded = Turbopuffer::Internal::Util.decode_content(headers, stream: stream)
524
- case req
525
- in {stream: Class => st}
526
- st.new(
527
- model: model,
528
- url: url,
529
- status: status,
530
- headers: headers,
531
- response: response,
532
- unwrap: unwrap,
533
- stream: decoded
534
- )
535
- in {page: Class => page}
536
- page.new(client: self, req: req, headers: headers, page_data: decoded)
537
- else
538
- unwrapped = Turbopuffer::Internal::Util.dig(decoded, unwrap)
539
- Turbopuffer::Internal::Type::Converter.coerce(model, unwrapped)
540
- end
546
+ parsed =
547
+ case req
548
+ in {stream: Class => st}
549
+ st.new(
550
+ model: model,
551
+ url: url,
552
+ status: status,
553
+ headers: headers,
554
+ response: response,
555
+ unwrap: unwrap,
556
+ stream: decoded
557
+ )
558
+ in {page: Class => page}
559
+ page.new(client: self, req: req, headers: headers, page_data: decoded)
560
+ else
561
+ unwrapped = Turbopuffer::Internal::Util.dig(decoded, unwrap)
562
+ Turbopuffer::Internal::Type::Converter.coerce(model, unwrapped)
563
+ end
564
+ # streamed responses are read by the caller, so they never finish
565
+ observation&.finish(response: response, parsed: parsed) unless req[:stream]
566
+ parsed
567
+ rescue Exception => e # rubocop:disable Lint/RescueException
568
+ observation&.finish(error: e)
569
+ raise
541
570
  end
542
571
 
543
572
  # @api private
@@ -13,6 +13,46 @@ module Turbopuffer
13
13
 
14
14
  DEFAULT_MAX_CONNECTIONS = [Etc.nprocessors, 99].max
15
15
 
16
+ # @api private
17
+ #
18
+ # Records connect timings while an observed attempt has the connection checked
19
+ # out.
20
+ module ObservedConnection
21
+ # @return [Turbopuffer::Internal::Transport::RequestObserver::Timings, nil]
22
+ attr_accessor :request_timings
23
+
24
+ # @api private
25
+ #
26
+ # Also catches the reconnects `Net::HTTP` does silently.
27
+ private def connect
28
+ timings = request_timings
29
+ return super if timings.nil?
30
+
31
+ timings.reused = false
32
+ timings.connect_end = nil
33
+ timings.connect_begin = Turbopuffer::Internal::Transport::RequestObserver.now
34
+ super.tap { timings.connect_end = Turbopuffer::Internal::Transport::RequestObserver.now }
35
+ end
36
+ end
37
+
38
+ # @api private
39
+ #
40
+ # Records when the request headers and body are written.
41
+ class ObservedRequest < Net::HTTPGenericRequest
42
+ # @return [Turbopuffer::Internal::Transport::RequestObserver::Timings, nil]
43
+ attr_accessor :request_timings
44
+
45
+ # @api private
46
+ #
47
+ # @param sock [Net::BufferedIO]
48
+ # @param ver [String]
49
+ # @param path [String]
50
+ def exec(sock, ver, path)
51
+ @request_timings&.send_begin = Turbopuffer::Internal::Transport::RequestObserver.now
52
+ super.tap { @request_timings&.send_end = Turbopuffer::Internal::Transport::RequestObserver.now }
53
+ end
54
+ end
55
+
16
56
  class << self
17
57
  # @api private
18
58
  #
@@ -48,6 +88,21 @@ module Turbopuffer
48
88
  conn.open_timeout = conn.read_timeout = conn.write_timeout = conn.continue_timeout = timeout
49
89
  end
50
90
 
91
+ # @api private
92
+ #
93
+ # @param conn [Net::HTTP]
94
+ # @param timings [Turbopuffer::Internal::Transport::RequestObserver::Timings, nil]
95
+ def observe_connection(conn, timings)
96
+ observed = conn.is_a?(self::ObservedConnection)
97
+ if timings
98
+ conn.extend(self::ObservedConnection) unless observed
99
+ conn.request_timings = timings
100
+ timings.reused = conn.started?
101
+ elsif observed
102
+ conn.request_timings = nil
103
+ end
104
+ end
105
+
51
106
  # @api private
52
107
  #
53
108
  # @param request [Hash{Symbol=>Object}] .
@@ -58,19 +113,23 @@ module Turbopuffer
58
113
  #
59
114
  # @option request [Hash{String=>String}] :headers
60
115
  #
116
+ # @option request [Turbopuffer::Internal::Transport::RequestObserver::Timings, nil] :timings
117
+ #
61
118
  # @param blk [Proc]
62
119
  #
63
120
  # @yieldparam [String]
64
121
  # @return [Array(Net::HTTPGenericRequest, Proc)]
65
122
  def build_request(request, &blk)
66
123
  method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
67
- req = Net::HTTPGenericRequest.new(
124
+ timings = request[:timings]
125
+ req = (timings ? self::ObservedRequest : Net::HTTPGenericRequest).new(
68
126
  method.to_s.upcase,
69
127
  !body.nil?,
70
128
  method != :head,
71
129
  URI(url.to_s) # ensure we construct a URI class of the right scheme
72
130
  )
73
131
 
132
+ req.request_timings = timings if timings
74
133
  headers.each { req[_1] = _2 }
75
134
 
76
135
  case body
@@ -126,9 +185,12 @@ module Turbopuffer
126
185
  #
127
186
  # @option request [Float] :deadline
128
187
  #
188
+ # @option request [Turbopuffer::Internal::Transport::RequestObserver::Timings, nil] :timings
189
+ #
129
190
  # @return [Array(Integer, Net::HTTPResponse, Enumerable<String>)]
130
191
  def execute(request)
131
192
  url, deadline = request.fetch_values(:url, :deadline)
193
+ timings = request[:timings]
132
194
 
133
195
  req = nil
134
196
  finished = false
@@ -142,6 +204,7 @@ module Turbopuffer
142
204
  closing = nil
143
205
  ::Thread.handle_interrupt(Object => :never) do
144
206
  ::Thread.handle_interrupt(Object => :immediate) do
207
+ self.class.observe_connection(conn, timings) if timings
145
208
  req, closing = self.class.build_request(request) do
146
209
  self.class.calibrate_socket_timeout(conn, deadline)
147
210
  end
@@ -155,6 +218,7 @@ module Turbopuffer
155
218
  self.class.calibrate_socket_timeout(conn, deadline)
156
219
  ::Kernel.catch(:jump) do
157
220
  conn.request(req) do |rsp|
221
+ timings&.response_headers = Turbopuffer::Internal::Transport::RequestObserver.now
158
222
  y << [req, rsp]
159
223
  ::Kernel.throw(:jump) if finished
160
224
 
@@ -164,6 +228,7 @@ module Turbopuffer
164
228
 
165
229
  self.class.calibrate_socket_timeout(conn, deadline)
166
230
  end
231
+ timings&.body_end = Turbopuffer::Internal::Transport::RequestObserver.now
167
232
  eof = true
168
233
  end
169
234
  end
@@ -172,6 +237,7 @@ module Turbopuffer
172
237
  begin
173
238
  conn.finish if !eof && conn&.started?
174
239
  ensure
240
+ self.class.observe_connection(conn, nil) if timings
175
241
  closing&.call
176
242
  end
177
243
  end
@@ -202,7 +268,16 @@ module Turbopuffer
202
268
  end
203
269
 
204
270
  define_sorbet_constant!(:Request) do
205
- T.type_alias { {method: Symbol, url: URI::Generic, headers: T::Hash[String, String], body: T.anything, deadline: Float} }
271
+ T.type_alias do
272
+ {
273
+ method: Symbol,
274
+ url: URI::Generic,
275
+ headers: T::Hash[String, String],
276
+ body: T.anything,
277
+ deadline: Float,
278
+ timings: T.nilable(Turbopuffer::Internal::Transport::RequestObserver::Timings)
279
+ }
280
+ end
206
281
  end
207
282
  end
208
283
  end
@@ -0,0 +1,377 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Turbopuffer
4
+ module Internal
5
+ module Transport
6
+ # @api private
7
+ #
8
+ # Called by the client at fixed points of every request. Custom code installs one
9
+ # with `BaseClient#request_observer=`. A single observer is shared across
10
+ # concurrent requests, so per-request state belongs on the scope returned by
11
+ # `#start`. Anything an observer raises is logged and ignored.
12
+ class RequestObserver
13
+ # rubocop:disable Lint/UnusedMethodArgument
14
+
15
+ # @api private
16
+ #
17
+ # Called once per logical request.
18
+ #
19
+ # @param info [Turbopuffer::Internal::Transport::RequestObserver::RequestInfo]
20
+ #
21
+ # @return [Turbopuffer::Internal::Transport::RequestObserver::RequestScope, nil] nil to not observe the request
22
+ def start(info) = nil
23
+
24
+ # @api private
25
+ #
26
+ # Observes a single logical request.
27
+ class RequestScope
28
+ # @api private
29
+ #
30
+ # Called before each attempt is sent. Changes to `request[:headers]` only apply to this attempt.
31
+ #
32
+ # @param attempt [Integer] 0-based
33
+ # @param request [Hash{Symbol=>Object}] `:method`, `:url`, `:headers` and `:body`
34
+ def attempt_begin(attempt, request) = nil
35
+
36
+ # @api private
37
+ #
38
+ # Called after each attempt, success or failure.
39
+ #
40
+ # @param result [Turbopuffer::Internal::Transport::RequestObserver::AttemptResult]
41
+ def attempt_end(result) = nil
42
+
43
+ # @api private
44
+ #
45
+ # Called at most once, after the response is parsed or when the request fails for good.
46
+ # Streamed responses don't finish.
47
+ #
48
+ # @param result [Turbopuffer::Internal::Transport::RequestObserver::RequestResult]
49
+ def finish(result) = nil
50
+ end
51
+
52
+ # rubocop:enable Lint/UnusedMethodArgument
53
+
54
+ # @api private
55
+ #
56
+ # @!attribute method
57
+ # @return [Symbol]
58
+ #
59
+ # @!attribute url
60
+ # The request path, e.g. `/v2/namespaces/a/query`.
61
+ # @return [String]
62
+ RequestInfo = Data.define(:method, :url)
63
+
64
+ # @api private
65
+ #
66
+ # `error_kind` is one of `:pool_timeout`, `:connect_timeout`, `:connect_error`, `:write_timeout`,
67
+ # `:read_timeout`, `:read_error`, `:timeout`, `:canceled` or `:other`, and nil without an error.
68
+ # `reached_server` is false when the attempt certainly never reached the server, true when a
69
+ # response arrived, and nil when unknown.
70
+ #
71
+ # @!attribute attempt
72
+ # @return [Integer]
73
+ #
74
+ # @!attribute request
75
+ # @return [Hash{Symbol=>Object}]
76
+ #
77
+ # @!attribute response
78
+ # @return [Net::HTTPResponse, nil]
79
+ #
80
+ # @!attribute error
81
+ # @return [Exception, nil]
82
+ #
83
+ # @!attribute error_kind
84
+ # @return [Symbol, nil]
85
+ #
86
+ # @!attribute reached_server
87
+ # @return [Boolean, nil]
88
+ #
89
+ # @!attribute timings
90
+ # @return [Turbopuffer::Internal::Transport::RequestObserver::Timings]
91
+ AttemptResult = Data.define(
92
+ :attempt,
93
+ :request,
94
+ :response,
95
+ :error,
96
+ :error_kind,
97
+ :reached_server,
98
+ :timings
99
+ )
100
+
101
+ # @api private
102
+ #
103
+ # `error_kind` is nil for HTTP status errors, which the response describes.
104
+ #
105
+ # @!attribute retries
106
+ # @return [Integer]
107
+ #
108
+ # @!attribute response
109
+ # @return [Net::HTTPResponse, nil]
110
+ #
111
+ # @!attribute error
112
+ # @return [Exception, nil]
113
+ #
114
+ # @!attribute error_kind
115
+ # @return [Symbol, nil]
116
+ #
117
+ # @!attribute parsed
118
+ # @return [Object, nil]
119
+ #
120
+ # @!attribute timings
121
+ # @return [Turbopuffer::Internal::Transport::RequestObserver::Timings]
122
+ RequestResult = Data.define(:retries, :response, :error, :error_kind, :parsed, :timings)
123
+
124
+ # @api private
125
+ #
126
+ # Monotonic timestamps of one attempt in integer nanoseconds, from `RequestObserver.now`. A field
127
+ # stays nil when its phase didn't happen or couldn't be observed. `extra` holds marks added by
128
+ # custom code.
129
+ class Timings
130
+ # @return [Integer, nil]
131
+ attr_accessor :attempt_begin,
132
+ :serialize_begin,
133
+ :serialize_end,
134
+ :request_ready,
135
+ :connect_begin,
136
+ :connect_end,
137
+ :send_begin,
138
+ :send_end,
139
+ :response_headers,
140
+ :body_end,
141
+ :deserialize_begin,
142
+ :deserialize_end
143
+
144
+ # Whether the attempt used an existing connection, nil when unknown.
145
+ #
146
+ # @return [Boolean, nil]
147
+ attr_accessor :reused
148
+
149
+ # @return [Hash{Symbol=>Object}]
150
+ attr_reader :extra
151
+
152
+ # @api private
153
+ def initialize
154
+ @extra = {}
155
+ end
156
+ end
157
+
158
+ # @api private
159
+ CONNECT_ERRORS = [
160
+ Net::OpenTimeout,
161
+ SocketError,
162
+ Errno::ECONNREFUSED,
163
+ Errno::EHOSTUNREACH,
164
+ Errno::ENETUNREACH
165
+ ].freeze
166
+
167
+ class << self
168
+ # @api private
169
+ #
170
+ # @return [Integer]
171
+ def now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
172
+
173
+ # @api private
174
+ #
175
+ # @param hook [Symbol]
176
+ # @param blk [Proc]
177
+ #
178
+ # @return [Object, nil]
179
+ def call_safely(hook, &blk)
180
+ blk.call
181
+ rescue StandardError => e
182
+ warn("Turbopuffer: request observer raised in `#{hook}`: #{e.class}: #{e.message}")
183
+ nil
184
+ end
185
+
186
+ # @api private
187
+ #
188
+ # @param error [Exception]
189
+ # @param timings [Turbopuffer::Internal::Transport::RequestObserver::Timings]
190
+ #
191
+ # @return [Symbol]
192
+ def error_kind(error, timings)
193
+ return :canceled unless error.is_a?(StandardError)
194
+
195
+ cause = (error.is_a?(Turbopuffer::Errors::APIConnectionError) && error.cause) || error
196
+ # a connect that started but never ended failed
197
+ connecting =
198
+ (!timings.connect_begin.nil? && timings.connect_end.nil?) ||
199
+ Turbopuffer::Internal::Transport::RequestObserver::CONNECT_ERRORS.any? { cause.is_a?(_1) }
200
+ case cause
201
+ in ConnectionPool::TimeoutError
202
+ :pool_timeout
203
+ in Timeout::Error | IO::TimeoutError | Errno::ETIMEDOUT if connecting
204
+ :connect_timeout
205
+ in _ if connecting
206
+ :connect_error
207
+ in Net::WriteTimeout
208
+ :write_timeout
209
+ in Net::ReadTimeout
210
+ :read_timeout
211
+ in Timeout::Error | IO::TimeoutError | Errno::ETIMEDOUT | Turbopuffer::Errors::APITimeoutError
212
+ :timeout
213
+ in EOFError | IOError | SystemCallError | OpenSSL::SSL::SSLError
214
+ :read_error
215
+ else
216
+ :other
217
+ end
218
+ end
219
+ end
220
+
221
+ # @api private
222
+ #
223
+ # Drives a scope through one logical request for the client.
224
+ class Observation
225
+ class << self
226
+ # @api private
227
+ #
228
+ # @param observer [Turbopuffer::Internal::Transport::RequestObserver]
229
+ # @param request [Hash{Symbol=>Object}]
230
+ # @param started_at [Integer]
231
+ # @param path [String] the interpolated path the request was made with
232
+ #
233
+ # @return [Turbopuffer::Internal::Transport::RequestObserver::Observation, nil]
234
+ def start(observer, request, started_at, path:)
235
+ built_at = Turbopuffer::Internal::Transport::RequestObserver.now
236
+ # the path as given keeps its own query, but not the request's query params
237
+ url = path.match?(%r{\A(/|[a-z][a-z\d+\-.]*://)}i) ? path : "/#{path}"
238
+ info = Turbopuffer::Internal::Transport::RequestObserver::RequestInfo.new(
239
+ method: request.fetch(:method), url: url
240
+ )
241
+ scope = Turbopuffer::Internal::Transport::RequestObserver.call_safely(:start) do
242
+ observer.start(info)
243
+ end
244
+ return nil if scope.nil?
245
+
246
+ new(scope, body: !request[:body].nil?, started_at: started_at, built_at: built_at)
247
+ end
248
+ end
249
+
250
+ # @api private
251
+ #
252
+ # @param input [Hash{Symbol=>Object}]
253
+ # @param retry_count [Integer]
254
+ #
255
+ # @return [Hash{Symbol=>Object}]
256
+ def attempt_begin(input, retry_count:)
257
+ @attempt += 1
258
+ @retries = retry_count
259
+ unless @attempt.zero?
260
+ @timings = Turbopuffer::Internal::Transport::RequestObserver::Timings.new
261
+ @timings.attempt_begin = Turbopuffer::Internal::Transport::RequestObserver.now
262
+ end
263
+
264
+ @timings.request_ready = Turbopuffer::Internal::Transport::RequestObserver.now
265
+ @request = {**input.slice(:method, :url, :body), headers: input.fetch(:headers).dup}
266
+ Turbopuffer::Internal::Transport::RequestObserver.call_safely(:attempt_begin) do
267
+ @scope.attempt_begin(@attempt, @request)
268
+ end
269
+
270
+ {**input, headers: @request.fetch(:headers), timings: @timings}
271
+ end
272
+
273
+ # @api private
274
+ #
275
+ # @param status [Integer, Exception]
276
+ # @param response [Net::HTTPResponse, nil]
277
+ def attempt_end(status, response)
278
+ error = status.is_a?(Exception) ? status : nil
279
+ error_kind = error && Turbopuffer::Internal::Transport::RequestObserver.error_kind(
280
+ error,
281
+ @timings
282
+ )
283
+ reached_server =
284
+ if response
285
+ true
286
+ elsif [:pool_timeout, :connect_timeout, :connect_error].include?(error_kind)
287
+ false
288
+ end
289
+
290
+ result = Turbopuffer::Internal::Transport::RequestObserver::AttemptResult.new(
291
+ attempt: @attempt,
292
+ request: @request,
293
+ response: response,
294
+ error: error,
295
+ error_kind: error_kind,
296
+ reached_server: reached_server,
297
+ timings: @timings
298
+ )
299
+ @request = nil
300
+ @response = response
301
+ Turbopuffer::Internal::Transport::RequestObserver.call_safely(:attempt_end) do
302
+ @scope.attempt_end(result)
303
+ end
304
+ end
305
+
306
+ # @api private
307
+ def deserialize_begin
308
+ @timings.deserialize_begin = Turbopuffer::Internal::Transport::RequestObserver.now
309
+ end
310
+
311
+ # @api private
312
+ #
313
+ # @param response [Net::HTTPResponse, nil] the response the request ended with, if it
314
+ # replaced the last attempt's
315
+ # @param parsed [Object, nil]
316
+ # @param error [Exception, nil]
317
+ def finish(response: nil, parsed: nil, error: nil)
318
+ return if @finished
319
+ @finished = true
320
+
321
+ # the attempt in flight was interrupted, e.g. by a non-`StandardError`
322
+ attempt_end(error, nil) if @request && error
323
+ unless @timings.deserialize_begin.nil?
324
+ @timings.deserialize_end = Turbopuffer::Internal::Transport::RequestObserver.now
325
+ end
326
+ # the body is read lazily while decoding, so deserializing starts once it's read
327
+ body_end = @timings.body_end
328
+ deserialize_begin = @timings.deserialize_begin
329
+ if body_end && deserialize_begin && body_end > deserialize_begin
330
+ @timings.deserialize_begin = body_end
331
+ end
332
+
333
+ error_kind =
334
+ case error
335
+ in nil | Turbopuffer::Errors::APIStatusError
336
+ nil
337
+ else
338
+ Turbopuffer::Internal::Transport::RequestObserver.error_kind(error, @timings)
339
+ end
340
+ result = Turbopuffer::Internal::Transport::RequestObserver::RequestResult.new(
341
+ retries: @retries,
342
+ response: response || @response,
343
+ error: error,
344
+ error_kind: error_kind,
345
+ parsed: parsed,
346
+ timings: @timings
347
+ )
348
+ Turbopuffer::Internal::Transport::RequestObserver.call_safely(:finish) do
349
+ @scope.finish(result)
350
+ end
351
+ end
352
+
353
+ # @api private
354
+ #
355
+ # @param scope [Turbopuffer::Internal::Transport::RequestObserver::RequestScope]
356
+ # @param body [Boolean]
357
+ # @param started_at [Integer]
358
+ # @param built_at [Integer]
359
+ def initialize(scope, body:, started_at:, built_at:)
360
+ @scope = scope
361
+ @attempt = -1
362
+ @retries = 0
363
+ @request = nil
364
+ @response = nil
365
+ @finished = false
366
+ @timings = Turbopuffer::Internal::Transport::RequestObserver::Timings.new
367
+ @timings.attempt_begin = started_at
368
+ return unless body
369
+
370
+ @timings.serialize_begin = started_at
371
+ @timings.serialize_end = built_at
372
+ end
373
+ end
374
+ end
375
+ end
376
+ end
377
+ end
@@ -96,6 +96,7 @@ module Turbopuffer
96
96
  module Ann
97
97
  extend Turbopuffer::Internal::Type::Union
98
98
 
99
+ # Whether to create an ANN index with the default configuration.
99
100
  variant Turbopuffer::Internal::Type::Boolean
100
101
 
101
102
  # Configuration options for ANN (Approximate Nearest Neighbor) indexing.
@@ -9,6 +9,7 @@ module Turbopuffer
9
9
  # The namespace to create an instant, copy-on-write clone of.
10
10
  variant String
11
11
 
12
+ # Configuration for branching from another namespace.
12
13
  variant -> { Turbopuffer::BranchFromNamespaceParams::BranchFromNamespaceConfig }
13
14
 
14
15
  class BranchFromNamespaceConfig < Turbopuffer::Internal::Type::BaseModel
@@ -19,6 +20,8 @@ module Turbopuffer
19
20
  required :source_namespace, String
20
21
 
21
22
  # @!method initialize(source_namespace:)
23
+ # Configuration for branching from another namespace.
24
+ #
22
25
  # @param source_namespace [String] The namespace to create an instant, copy-on-write clone of.
23
26
  end
24
27