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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +9 -0
- data/README.md +15 -1
- data/lib/turbopuffer/client.rb +7 -0
- data/lib/turbopuffer/internal/respond_async.rb +1 -1
- data/lib/turbopuffer/internal/telemetry.rb +462 -0
- data/lib/turbopuffer/internal/transport/base_client.rb +50 -21
- data/lib/turbopuffer/internal/transport/pooled_net_requester.rb +77 -2
- data/lib/turbopuffer/internal/transport/request_observer.rb +377 -0
- data/lib/turbopuffer/models/attribute_schema_config.rb +1 -0
- data/lib/turbopuffer/models/branch_from_namespace_params.rb +3 -0
- data/lib/turbopuffer/models/copy_from_namespace_operation.rb +8 -1
- data/lib/turbopuffer/models/copy_from_namespace_operation_result.rb +5 -3
- data/lib/turbopuffer/models/copy_from_namespace_params.rb +3 -0
- data/lib/turbopuffer/models/full_text_search.rb +1 -0
- data/lib/turbopuffer/models/id.rb +1 -1
- data/lib/turbopuffer/models/namespace_hint_cache_warm_response.rb +2 -1
- data/lib/turbopuffer/models/namespace_metadata.rb +10 -1
- data/lib/turbopuffer/models/namespace_metadata_patch.rb +1 -0
- data/lib/turbopuffer/models/namespace_multi_query_params.rb +1 -0
- data/lib/turbopuffer/models/namespace_multi_query_response.rb +19 -2
- data/lib/turbopuffer/models/namespace_query_response.rb +10 -2
- data/lib/turbopuffer/models/namespace_recall_response.rb +5 -0
- data/lib/turbopuffer/models/namespace_start_copy_from_response.rb +2 -0
- data/lib/turbopuffer/models/namespace_write_params.rb +3 -3
- data/lib/turbopuffer/models/operation_error.rb +2 -0
- data/lib/turbopuffer/models/write_result.rb +1 -1
- data/lib/turbopuffer/resources/namespaces.rb +1 -1
- data/lib/turbopuffer/version.rb +1 -1
- data/lib/turbopuffer.rb +2 -0
- data/rbi/turbopuffer/client.rbi +5 -0
- data/rbi/turbopuffer/internal/telemetry.rbi +275 -0
- data/rbi/turbopuffer/internal/transport/base_client.rbi +13 -2
- data/rbi/turbopuffer/internal/transport/pooled_net_requester.rbi +47 -1
- data/rbi/turbopuffer/internal/transport/request_observer.rbi +340 -0
- data/rbi/turbopuffer/models/branch_from_namespace_params.rbi +1 -0
- data/rbi/turbopuffer/models/copy_from_namespace_operation.rbi +4 -0
- data/rbi/turbopuffer/models/copy_from_namespace_operation_result.rbi +8 -3
- data/rbi/turbopuffer/models/copy_from_namespace_params.rbi +1 -0
- data/rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi +2 -0
- data/rbi/turbopuffer/models/namespace_metadata.rbi +5 -0
- data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
- data/rbi/turbopuffer/models/namespace_query_response.rbi +8 -1
- data/rbi/turbopuffer/models/namespace_recall_response.rbi +4 -0
- data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi +1 -0
- data/rbi/turbopuffer/models/namespace_write_params.rbi +3 -3
- data/rbi/turbopuffer/models/operation_error.rbi +1 -0
- data/rbi/turbopuffer/models/write_result.rbi +1 -1
- data/rbi/turbopuffer/resources/namespaces.rbi +2 -1
- data/sig/turbopuffer/client.rbs +1 -0
- data/sig/turbopuffer/internal/telemetry.rbs +129 -0
- data/sig/turbopuffer/internal/transport/base_client.rbs +5 -1
- data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs +15 -1
- data/sig/turbopuffer/internal/transport/request_observer.rbs +153 -0
- metadata +8 -2
|
@@ -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
|
-
|
|
525
|
-
|
|
526
|
-
st
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
page
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|