turbopuffer 2.7.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 +22 -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_params.rb +9 -1
- 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/rerank_model_params.rb +38 -0
- data/lib/turbopuffer/models/write_result.rb +1 -1
- data/lib/turbopuffer/models.rb +2 -0
- data/lib/turbopuffer/resources/namespaces.rb +4 -2
- data/lib/turbopuffer/version.rb +1 -1
- data/lib/turbopuffer.rb +3 -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_params.rbi +11 -0
- 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/rerank_model_params.rbi +48 -0
- data/rbi/turbopuffer/models/write_result.rbi +1 -1
- data/rbi/turbopuffer/models.rbi +2 -0
- data/rbi/turbopuffer/resources/namespaces.rbi +5 -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
- data/sig/turbopuffer/models/namespace_query_params.rbs +9 -0
- data/sig/turbopuffer/models/rerank_model_params.rbs +18 -0
- data/sig/turbopuffer/models.rbs +2 -0
- data/sig/turbopuffer/resources/namespaces.rbs +1 -0
- metadata +11 -2
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
# typed: strong
|
|
2
|
+
|
|
3
|
+
module Turbopuffer
|
|
4
|
+
module Internal
|
|
5
|
+
# Client telemetry reported to turbopuffer on subsequent requests.
|
|
6
|
+
#
|
|
7
|
+
# @api private
|
|
8
|
+
module Telemetry
|
|
9
|
+
ENV_VAR = T.let(T.unsafe(nil), String)
|
|
10
|
+
HEADER = T.let(T.unsafe(nil), String)
|
|
11
|
+
SAMPLE_RATE_HEADER = T.let(T.unsafe(nil), String)
|
|
12
|
+
|
|
13
|
+
ENVELOPE_VERSION = T.let(T.unsafe(nil), Integer)
|
|
14
|
+
|
|
15
|
+
MAX_RECORDS_PER_HEADER = T.let(T.unsafe(nil), Integer)
|
|
16
|
+
MAX_BUFFERED_RECORDS = T.let(T.unsafe(nil), Integer)
|
|
17
|
+
|
|
18
|
+
TRUE_VALUES = T.let(T.unsafe(nil), T::Array[String])
|
|
19
|
+
FALSE_VALUES = T.let(T.unsafe(nil), T::Array[String])
|
|
20
|
+
|
|
21
|
+
NAMESPACE_RE = T.let(T.unsafe(nil), Regexp)
|
|
22
|
+
OPERATION_RE = T.let(T.unsafe(nil), Regexp)
|
|
23
|
+
SCHEME_AND_HOST_RE = T.let(T.unsafe(nil), Regexp)
|
|
24
|
+
|
|
25
|
+
class << self
|
|
26
|
+
# @api private
|
|
27
|
+
#
|
|
28
|
+
# Resolves whether telemetry is enabled, preferring an explicit value over the environment.
|
|
29
|
+
sig { params(value: T.nilable(T::Boolean)).returns(T::Boolean) }
|
|
30
|
+
def resolve_enabled(value)
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# @api private
|
|
34
|
+
#
|
|
35
|
+
# Returns the method and path of a request with identifiers like the namespace replaced.
|
|
36
|
+
sig do
|
|
37
|
+
params(
|
|
38
|
+
method: T.any(Symbol, String),
|
|
39
|
+
url: T.any(URI::Generic, String)
|
|
40
|
+
).returns(String)
|
|
41
|
+
end
|
|
42
|
+
def route_template(method, url)
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# @api private
|
|
46
|
+
#
|
|
47
|
+
# Returns the duration in nanoseconds of each client-side phase of an attempt ending at
|
|
48
|
+
# `end_at`. Phases that weren't observed are left out.
|
|
49
|
+
sig do
|
|
50
|
+
params(
|
|
51
|
+
timings: Turbopuffer::Internal::Transport::RequestObserver::Timings,
|
|
52
|
+
end_at: Integer
|
|
53
|
+
).returns(T::Hash[Symbol, Integer])
|
|
54
|
+
end
|
|
55
|
+
def compute_durations(timings, end_at)
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# @api private
|
|
59
|
+
sig { returns(Float) }
|
|
60
|
+
def random
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
# @api private
|
|
64
|
+
#
|
|
65
|
+
# Returns the buffer shared by clients with the same API key and base URL, or nil if
|
|
66
|
+
# telemetry is disabled.
|
|
67
|
+
sig do
|
|
68
|
+
params(
|
|
69
|
+
enabled: T.nilable(T::Boolean),
|
|
70
|
+
api_key: String,
|
|
71
|
+
base_url: String
|
|
72
|
+
).returns(T.nilable(Turbopuffer::Internal::Telemetry::Buffer))
|
|
73
|
+
end
|
|
74
|
+
def buffer_for(enabled, api_key, base_url)
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# @api private
|
|
78
|
+
sig { void }
|
|
79
|
+
def after_fork_in_child
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
sig { void }
|
|
83
|
+
private def install_fork_hook
|
|
84
|
+
end
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
# @api private
|
|
88
|
+
#
|
|
89
|
+
# Records taken from a buffer, encoded as a header value.
|
|
90
|
+
class Batch
|
|
91
|
+
sig { returns(T::Array[[Integer, T::Hash[Symbol, T.anything]]]) }
|
|
92
|
+
attr_reader :records
|
|
93
|
+
|
|
94
|
+
sig { returns(Integer) }
|
|
95
|
+
attr_reader :dropped
|
|
96
|
+
|
|
97
|
+
sig { returns(String) }
|
|
98
|
+
attr_reader :header
|
|
99
|
+
|
|
100
|
+
# @api private
|
|
101
|
+
sig do
|
|
102
|
+
params(
|
|
103
|
+
records: T::Array[[Integer, T::Hash[Symbol, T.anything]]],
|
|
104
|
+
dropped: Integer
|
|
105
|
+
).returns(T.attached_class)
|
|
106
|
+
end
|
|
107
|
+
def self.new(records, dropped)
|
|
108
|
+
end
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
# @api private
|
|
112
|
+
#
|
|
113
|
+
# Buffers per-request telemetry records until a later request can carry them.
|
|
114
|
+
class Buffer
|
|
115
|
+
sig { returns(Float) }
|
|
116
|
+
attr_reader :sample_rate
|
|
117
|
+
|
|
118
|
+
# @api private
|
|
119
|
+
sig { returns(T.attached_class) }
|
|
120
|
+
def self.new
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
# @api private
|
|
124
|
+
#
|
|
125
|
+
# Adopts the sample rate advertised by the server, ignoring invalid values.
|
|
126
|
+
sig { params(response: Net::HTTPResponse).void }
|
|
127
|
+
def observe_response(response)
|
|
128
|
+
end
|
|
129
|
+
|
|
130
|
+
# @api private
|
|
131
|
+
#
|
|
132
|
+
# Samples and buffers a record for one request.
|
|
133
|
+
sig do
|
|
134
|
+
params(
|
|
135
|
+
method: T.any(Symbol, String),
|
|
136
|
+
url: T.any(URI::Generic, String),
|
|
137
|
+
status: Integer,
|
|
138
|
+
retries: Integer,
|
|
139
|
+
durations: T::Hash[Symbol, Integer],
|
|
140
|
+
server_total_ms: T.nilable(Numeric),
|
|
141
|
+
error: T.nilable(String),
|
|
142
|
+
reused: T.nilable(T::Boolean)
|
|
143
|
+
).void
|
|
144
|
+
end
|
|
145
|
+
def record(
|
|
146
|
+
method:,
|
|
147
|
+
url:,
|
|
148
|
+
status:,
|
|
149
|
+
retries:,
|
|
150
|
+
durations:,
|
|
151
|
+
server_total_ms: nil,
|
|
152
|
+
error: nil,
|
|
153
|
+
reused: nil
|
|
154
|
+
)
|
|
155
|
+
end
|
|
156
|
+
|
|
157
|
+
# @api private
|
|
158
|
+
#
|
|
159
|
+
# Removes up to `MAX_RECORDS_PER_HEADER` of the oldest records.
|
|
160
|
+
sig { returns(T.nilable(Turbopuffer::Internal::Telemetry::Batch)) }
|
|
161
|
+
def take
|
|
162
|
+
end
|
|
163
|
+
|
|
164
|
+
# @api private
|
|
165
|
+
#
|
|
166
|
+
# Returns a batch that never reached the server to the front of the buffer.
|
|
167
|
+
sig { params(batch: Turbopuffer::Internal::Telemetry::Batch).void }
|
|
168
|
+
def restore(batch)
|
|
169
|
+
end
|
|
170
|
+
|
|
171
|
+
# @api private
|
|
172
|
+
sig { void }
|
|
173
|
+
def reset_after_fork
|
|
174
|
+
end
|
|
175
|
+
end
|
|
176
|
+
|
|
177
|
+
# @api private
|
|
178
|
+
#
|
|
179
|
+
# Installs the request observer that records telemetry for a client.
|
|
180
|
+
class Observer < Turbopuffer::Internal::Transport::RequestObserver
|
|
181
|
+
sig { returns(Turbopuffer::Internal::Telemetry::Buffer) }
|
|
182
|
+
attr_reader :buffer
|
|
183
|
+
|
|
184
|
+
# @api private
|
|
185
|
+
sig do
|
|
186
|
+
params(buffer: Turbopuffer::Internal::Telemetry::Buffer).returns(
|
|
187
|
+
T.attached_class
|
|
188
|
+
)
|
|
189
|
+
end
|
|
190
|
+
def self.new(buffer)
|
|
191
|
+
end
|
|
192
|
+
|
|
193
|
+
# @api private
|
|
194
|
+
sig do
|
|
195
|
+
params(
|
|
196
|
+
info: Turbopuffer::Internal::Transport::RequestObserver::RequestInfo
|
|
197
|
+
).returns(Turbopuffer::Internal::Telemetry::Scope)
|
|
198
|
+
end
|
|
199
|
+
def start(info)
|
|
200
|
+
end
|
|
201
|
+
end
|
|
202
|
+
|
|
203
|
+
# @api private
|
|
204
|
+
class Scope < Turbopuffer::Internal::Transport::RequestObserver::RequestScope
|
|
205
|
+
# @api private
|
|
206
|
+
sig do
|
|
207
|
+
params(
|
|
208
|
+
buffer: Turbopuffer::Internal::Telemetry::Buffer,
|
|
209
|
+
info: Turbopuffer::Internal::Transport::RequestObserver::RequestInfo
|
|
210
|
+
).returns(T.attached_class)
|
|
211
|
+
end
|
|
212
|
+
def self.new(buffer, info)
|
|
213
|
+
end
|
|
214
|
+
|
|
215
|
+
# @api private
|
|
216
|
+
sig do
|
|
217
|
+
params(attempt: Integer, request: T::Hash[Symbol, T.anything]).void
|
|
218
|
+
end
|
|
219
|
+
def attempt_begin(attempt, request)
|
|
220
|
+
end
|
|
221
|
+
|
|
222
|
+
# @api private
|
|
223
|
+
sig do
|
|
224
|
+
params(
|
|
225
|
+
result:
|
|
226
|
+
Turbopuffer::Internal::Transport::RequestObserver::AttemptResult
|
|
227
|
+
).void
|
|
228
|
+
end
|
|
229
|
+
def attempt_end(result)
|
|
230
|
+
end
|
|
231
|
+
|
|
232
|
+
# @api private
|
|
233
|
+
sig do
|
|
234
|
+
params(
|
|
235
|
+
result:
|
|
236
|
+
Turbopuffer::Internal::Transport::RequestObserver::RequestResult
|
|
237
|
+
).void
|
|
238
|
+
end
|
|
239
|
+
def finish(result)
|
|
240
|
+
end
|
|
241
|
+
|
|
242
|
+
sig do
|
|
243
|
+
params(
|
|
244
|
+
result:
|
|
245
|
+
Turbopuffer::Internal::Transport::RequestObserver::RequestResult
|
|
246
|
+
).returns(Integer)
|
|
247
|
+
end
|
|
248
|
+
private def status(result)
|
|
249
|
+
end
|
|
250
|
+
|
|
251
|
+
sig { params(kind: T.nilable(Symbol)).returns(T.nilable(String)) }
|
|
252
|
+
private def error_name(kind)
|
|
253
|
+
end
|
|
254
|
+
|
|
255
|
+
sig { params(parsed: T.anything).returns(T.nilable(Numeric)) }
|
|
256
|
+
private def server_total_ms(parsed)
|
|
257
|
+
end
|
|
258
|
+
|
|
259
|
+
sig { params(value: T.anything, name: Symbol).returns(T.anything) }
|
|
260
|
+
private def field(value, name)
|
|
261
|
+
end
|
|
262
|
+
end
|
|
263
|
+
|
|
264
|
+
# @api private
|
|
265
|
+
#
|
|
266
|
+
# Resets telemetry in forked children.
|
|
267
|
+
module ForkHook
|
|
268
|
+
# @api private
|
|
269
|
+
sig { returns(Integer) }
|
|
270
|
+
def _fork
|
|
271
|
+
end
|
|
272
|
+
end
|
|
273
|
+
end
|
|
274
|
+
end
|
|
275
|
+
end
|
|
@@ -142,6 +142,12 @@ module Turbopuffer
|
|
|
142
142
|
sig { returns(Turbopuffer::Internal::Transport::PooledNetRequester) }
|
|
143
143
|
attr_reader :requester
|
|
144
144
|
|
|
145
|
+
# @api private
|
|
146
|
+
sig do
|
|
147
|
+
returns(T.nilable(Turbopuffer::Internal::Transport::RequestObserver))
|
|
148
|
+
end
|
|
149
|
+
attr_accessor :request_observer
|
|
150
|
+
|
|
145
151
|
# @api private
|
|
146
152
|
sig do
|
|
147
153
|
params(
|
|
@@ -219,14 +225,19 @@ module Turbopuffer
|
|
|
219
225
|
request: Turbopuffer::Internal::Transport::BaseClient::RequestInput,
|
|
220
226
|
redirect_count: Integer,
|
|
221
227
|
retry_count: Integer,
|
|
222
|
-
send_retry_header: T::Boolean
|
|
228
|
+
send_retry_header: T::Boolean,
|
|
229
|
+
observation:
|
|
230
|
+
T.nilable(
|
|
231
|
+
Turbopuffer::Internal::Transport::RequestObserver::Observation
|
|
232
|
+
)
|
|
223
233
|
).returns([Integer, Net::HTTPResponse, T::Enumerable[String]])
|
|
224
234
|
end
|
|
225
235
|
def send_request(
|
|
226
236
|
request,
|
|
227
237
|
redirect_count:,
|
|
228
238
|
retry_count:,
|
|
229
|
-
send_retry_header
|
|
239
|
+
send_retry_header:,
|
|
240
|
+
observation: nil
|
|
230
241
|
)
|
|
231
242
|
end
|
|
232
243
|
|
|
@@ -14,7 +14,11 @@ module Turbopuffer
|
|
|
14
14
|
url: URI::Generic,
|
|
15
15
|
headers: T::Hash[String, String],
|
|
16
16
|
body: T.anything,
|
|
17
|
-
deadline: Float
|
|
17
|
+
deadline: Float,
|
|
18
|
+
timings:
|
|
19
|
+
T.nilable(
|
|
20
|
+
Turbopuffer::Internal::Transport::RequestObserver::Timings
|
|
21
|
+
)
|
|
18
22
|
}
|
|
19
23
|
end
|
|
20
24
|
|
|
@@ -24,6 +28,35 @@ module Turbopuffer
|
|
|
24
28
|
|
|
25
29
|
DEFAULT_MAX_CONNECTIONS = T.let(T.unsafe(nil), Integer)
|
|
26
30
|
|
|
31
|
+
# @api private
|
|
32
|
+
#
|
|
33
|
+
# Records connect timings while an observed attempt has the connection checked
|
|
34
|
+
# out.
|
|
35
|
+
module ObservedConnection
|
|
36
|
+
sig do
|
|
37
|
+
returns(
|
|
38
|
+
T.nilable(
|
|
39
|
+
Turbopuffer::Internal::Transport::RequestObserver::Timings
|
|
40
|
+
)
|
|
41
|
+
)
|
|
42
|
+
end
|
|
43
|
+
attr_accessor :request_timings
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# @api private
|
|
47
|
+
#
|
|
48
|
+
# Records when the request headers and body are written.
|
|
49
|
+
class ObservedRequest < Net::HTTPGenericRequest
|
|
50
|
+
sig do
|
|
51
|
+
returns(
|
|
52
|
+
T.nilable(
|
|
53
|
+
Turbopuffer::Internal::Transport::RequestObserver::Timings
|
|
54
|
+
)
|
|
55
|
+
)
|
|
56
|
+
end
|
|
57
|
+
attr_accessor :request_timings
|
|
58
|
+
end
|
|
59
|
+
|
|
27
60
|
class << self
|
|
28
61
|
# @api private
|
|
29
62
|
sig do
|
|
@@ -39,6 +72,19 @@ module Turbopuffer
|
|
|
39
72
|
def calibrate_socket_timeout(conn, deadline)
|
|
40
73
|
end
|
|
41
74
|
|
|
75
|
+
# @api private
|
|
76
|
+
sig do
|
|
77
|
+
params(
|
|
78
|
+
conn: Net::HTTP,
|
|
79
|
+
timings:
|
|
80
|
+
T.nilable(
|
|
81
|
+
Turbopuffer::Internal::Transport::RequestObserver::Timings
|
|
82
|
+
)
|
|
83
|
+
).void
|
|
84
|
+
end
|
|
85
|
+
def observe_connection(conn, timings)
|
|
86
|
+
end
|
|
87
|
+
|
|
42
88
|
# @api private
|
|
43
89
|
sig do
|
|
44
90
|
params(
|
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
# typed: strong
|
|
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
|
+
# @api private
|
|
14
|
+
#
|
|
15
|
+
# Called once per logical request. Returns nil to not observe the request.
|
|
16
|
+
sig do
|
|
17
|
+
params(
|
|
18
|
+
info: Turbopuffer::Internal::Transport::RequestObserver::RequestInfo
|
|
19
|
+
).returns(
|
|
20
|
+
T.nilable(
|
|
21
|
+
Turbopuffer::Internal::Transport::RequestObserver::RequestScope
|
|
22
|
+
)
|
|
23
|
+
)
|
|
24
|
+
end
|
|
25
|
+
def start(info)
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
# @api private
|
|
29
|
+
#
|
|
30
|
+
# Observes a single logical request.
|
|
31
|
+
class RequestScope
|
|
32
|
+
# @api private
|
|
33
|
+
#
|
|
34
|
+
# Called before each attempt is sent. Changes to `request[:headers]` only apply to this attempt.
|
|
35
|
+
sig do
|
|
36
|
+
params(attempt: Integer, request: T::Hash[Symbol, T.anything]).void
|
|
37
|
+
end
|
|
38
|
+
def attempt_begin(attempt, request)
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# @api private
|
|
42
|
+
#
|
|
43
|
+
# Called after each attempt, success or failure.
|
|
44
|
+
sig do
|
|
45
|
+
params(
|
|
46
|
+
result:
|
|
47
|
+
Turbopuffer::Internal::Transport::RequestObserver::AttemptResult
|
|
48
|
+
).void
|
|
49
|
+
end
|
|
50
|
+
def attempt_end(result)
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# @api private
|
|
54
|
+
#
|
|
55
|
+
# Called at most once, after the response is parsed or when the request fails for good.
|
|
56
|
+
# Streamed responses don't finish.
|
|
57
|
+
sig do
|
|
58
|
+
params(
|
|
59
|
+
result:
|
|
60
|
+
Turbopuffer::Internal::Transport::RequestObserver::RequestResult
|
|
61
|
+
).void
|
|
62
|
+
end
|
|
63
|
+
def finish(result)
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# @api private
|
|
68
|
+
class RequestInfo
|
|
69
|
+
sig { returns(Symbol) }
|
|
70
|
+
def method
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
# The request path, e.g. `/v2/namespaces/a/query`.
|
|
74
|
+
sig { returns(String) }
|
|
75
|
+
def url
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
sig { params(method: Symbol, url: String).returns(T.attached_class) }
|
|
79
|
+
def self.new(method:, url:)
|
|
80
|
+
end
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# @api private
|
|
84
|
+
class AttemptResult
|
|
85
|
+
sig { returns(Integer) }
|
|
86
|
+
def attempt
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
sig { returns(T::Hash[Symbol, T.anything]) }
|
|
90
|
+
def request
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
sig { returns(T.nilable(Net::HTTPResponse)) }
|
|
94
|
+
def response
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
sig { returns(T.nilable(Exception)) }
|
|
98
|
+
def error
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
sig { returns(T.nilable(Symbol)) }
|
|
102
|
+
def error_kind
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
sig { returns(T.nilable(T::Boolean)) }
|
|
106
|
+
def reached_server
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
sig do
|
|
110
|
+
returns(Turbopuffer::Internal::Transport::RequestObserver::Timings)
|
|
111
|
+
end
|
|
112
|
+
def timings
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
sig do
|
|
116
|
+
params(
|
|
117
|
+
attempt: Integer,
|
|
118
|
+
request: T::Hash[Symbol, T.anything],
|
|
119
|
+
response: T.nilable(Net::HTTPResponse),
|
|
120
|
+
error: T.nilable(Exception),
|
|
121
|
+
error_kind: T.nilable(Symbol),
|
|
122
|
+
reached_server: T.nilable(T::Boolean),
|
|
123
|
+
timings:
|
|
124
|
+
Turbopuffer::Internal::Transport::RequestObserver::Timings
|
|
125
|
+
).returns(T.attached_class)
|
|
126
|
+
end
|
|
127
|
+
def self.new(
|
|
128
|
+
attempt:,
|
|
129
|
+
request:,
|
|
130
|
+
response:,
|
|
131
|
+
error:,
|
|
132
|
+
error_kind:,
|
|
133
|
+
reached_server:,
|
|
134
|
+
timings:
|
|
135
|
+
)
|
|
136
|
+
end
|
|
137
|
+
end
|
|
138
|
+
|
|
139
|
+
# @api private
|
|
140
|
+
class RequestResult
|
|
141
|
+
sig { returns(Integer) }
|
|
142
|
+
def retries
|
|
143
|
+
end
|
|
144
|
+
|
|
145
|
+
sig { returns(T.nilable(Net::HTTPResponse)) }
|
|
146
|
+
def response
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
sig { returns(T.nilable(Exception)) }
|
|
150
|
+
def error
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
sig { returns(T.nilable(Symbol)) }
|
|
154
|
+
def error_kind
|
|
155
|
+
end
|
|
156
|
+
|
|
157
|
+
sig { returns(T.anything) }
|
|
158
|
+
def parsed
|
|
159
|
+
end
|
|
160
|
+
|
|
161
|
+
sig do
|
|
162
|
+
returns(Turbopuffer::Internal::Transport::RequestObserver::Timings)
|
|
163
|
+
end
|
|
164
|
+
def timings
|
|
165
|
+
end
|
|
166
|
+
|
|
167
|
+
sig do
|
|
168
|
+
params(
|
|
169
|
+
retries: Integer,
|
|
170
|
+
response: T.nilable(Net::HTTPResponse),
|
|
171
|
+
error: T.nilable(Exception),
|
|
172
|
+
error_kind: T.nilable(Symbol),
|
|
173
|
+
parsed: T.anything,
|
|
174
|
+
timings:
|
|
175
|
+
Turbopuffer::Internal::Transport::RequestObserver::Timings
|
|
176
|
+
).returns(T.attached_class)
|
|
177
|
+
end
|
|
178
|
+
def self.new(
|
|
179
|
+
retries:,
|
|
180
|
+
response:,
|
|
181
|
+
error:,
|
|
182
|
+
error_kind:,
|
|
183
|
+
parsed:,
|
|
184
|
+
timings:
|
|
185
|
+
)
|
|
186
|
+
end
|
|
187
|
+
end
|
|
188
|
+
|
|
189
|
+
# @api private
|
|
190
|
+
#
|
|
191
|
+
# Monotonic timestamps of one attempt in integer nanoseconds, from `RequestObserver.now`.
|
|
192
|
+
class Timings
|
|
193
|
+
sig { returns(T.nilable(Integer)) }
|
|
194
|
+
attr_accessor :attempt_begin
|
|
195
|
+
|
|
196
|
+
sig { returns(T.nilable(Integer)) }
|
|
197
|
+
attr_accessor :serialize_begin
|
|
198
|
+
|
|
199
|
+
sig { returns(T.nilable(Integer)) }
|
|
200
|
+
attr_accessor :serialize_end
|
|
201
|
+
|
|
202
|
+
sig { returns(T.nilable(Integer)) }
|
|
203
|
+
attr_accessor :request_ready
|
|
204
|
+
|
|
205
|
+
sig { returns(T.nilable(Integer)) }
|
|
206
|
+
attr_accessor :connect_begin
|
|
207
|
+
|
|
208
|
+
sig { returns(T.nilable(Integer)) }
|
|
209
|
+
attr_accessor :connect_end
|
|
210
|
+
|
|
211
|
+
sig { returns(T.nilable(Integer)) }
|
|
212
|
+
attr_accessor :send_begin
|
|
213
|
+
|
|
214
|
+
sig { returns(T.nilable(Integer)) }
|
|
215
|
+
attr_accessor :send_end
|
|
216
|
+
|
|
217
|
+
sig { returns(T.nilable(Integer)) }
|
|
218
|
+
attr_accessor :response_headers
|
|
219
|
+
|
|
220
|
+
sig { returns(T.nilable(Integer)) }
|
|
221
|
+
attr_accessor :body_end
|
|
222
|
+
|
|
223
|
+
sig { returns(T.nilable(Integer)) }
|
|
224
|
+
attr_accessor :deserialize_begin
|
|
225
|
+
|
|
226
|
+
sig { returns(T.nilable(Integer)) }
|
|
227
|
+
attr_accessor :deserialize_end
|
|
228
|
+
|
|
229
|
+
# Whether the attempt used an existing connection, nil when unknown.
|
|
230
|
+
sig { returns(T.nilable(T::Boolean)) }
|
|
231
|
+
attr_accessor :reused
|
|
232
|
+
|
|
233
|
+
sig { returns(T::Hash[Symbol, T.anything]) }
|
|
234
|
+
attr_reader :extra
|
|
235
|
+
|
|
236
|
+
# @api private
|
|
237
|
+
sig { returns(T.attached_class) }
|
|
238
|
+
def self.new
|
|
239
|
+
end
|
|
240
|
+
end
|
|
241
|
+
|
|
242
|
+
# @api private
|
|
243
|
+
CONNECT_ERRORS = T.let(T.unsafe(nil), T::Array[T::Class[Exception]])
|
|
244
|
+
|
|
245
|
+
class << self
|
|
246
|
+
# @api private
|
|
247
|
+
sig { returns(Integer) }
|
|
248
|
+
def now
|
|
249
|
+
end
|
|
250
|
+
|
|
251
|
+
# @api private
|
|
252
|
+
sig do
|
|
253
|
+
params(hook: Symbol, blk: T.proc.returns(T.anything)).returns(
|
|
254
|
+
T.anything
|
|
255
|
+
)
|
|
256
|
+
end
|
|
257
|
+
def call_safely(hook, &blk)
|
|
258
|
+
end
|
|
259
|
+
|
|
260
|
+
# @api private
|
|
261
|
+
sig do
|
|
262
|
+
params(
|
|
263
|
+
error: Exception,
|
|
264
|
+
timings:
|
|
265
|
+
Turbopuffer::Internal::Transport::RequestObserver::Timings
|
|
266
|
+
).returns(Symbol)
|
|
267
|
+
end
|
|
268
|
+
def error_kind(error, timings)
|
|
269
|
+
end
|
|
270
|
+
end
|
|
271
|
+
|
|
272
|
+
# @api private
|
|
273
|
+
#
|
|
274
|
+
# Drives a scope through one logical request for the client.
|
|
275
|
+
class Observation
|
|
276
|
+
# @api private
|
|
277
|
+
sig do
|
|
278
|
+
params(
|
|
279
|
+
observer: Turbopuffer::Internal::Transport::RequestObserver,
|
|
280
|
+
request: T::Hash[Symbol, T.anything],
|
|
281
|
+
started_at: Integer,
|
|
282
|
+
path: String
|
|
283
|
+
).returns(T.nilable(T.attached_class))
|
|
284
|
+
end
|
|
285
|
+
def self.start(observer, request, started_at, path:)
|
|
286
|
+
end
|
|
287
|
+
|
|
288
|
+
# @api private
|
|
289
|
+
sig do
|
|
290
|
+
params(
|
|
291
|
+
input: T::Hash[Symbol, T.anything],
|
|
292
|
+
retry_count: Integer
|
|
293
|
+
).returns(T::Hash[Symbol, T.anything])
|
|
294
|
+
end
|
|
295
|
+
def attempt_begin(input, retry_count:)
|
|
296
|
+
end
|
|
297
|
+
|
|
298
|
+
# @api private
|
|
299
|
+
sig do
|
|
300
|
+
params(
|
|
301
|
+
status: T.any(Integer, Exception),
|
|
302
|
+
response: T.nilable(Net::HTTPResponse)
|
|
303
|
+
).void
|
|
304
|
+
end
|
|
305
|
+
def attempt_end(status, response)
|
|
306
|
+
end
|
|
307
|
+
|
|
308
|
+
# @api private
|
|
309
|
+
sig { void }
|
|
310
|
+
def deserialize_begin
|
|
311
|
+
end
|
|
312
|
+
|
|
313
|
+
# @api private
|
|
314
|
+
sig do
|
|
315
|
+
params(
|
|
316
|
+
response: T.nilable(Net::HTTPResponse),
|
|
317
|
+
parsed: T.anything,
|
|
318
|
+
error: T.nilable(Exception)
|
|
319
|
+
).void
|
|
320
|
+
end
|
|
321
|
+
def finish(response: nil, parsed: nil, error: nil)
|
|
322
|
+
end
|
|
323
|
+
|
|
324
|
+
# @api private
|
|
325
|
+
sig do
|
|
326
|
+
params(
|
|
327
|
+
scope:
|
|
328
|
+
Turbopuffer::Internal::Transport::RequestObserver::RequestScope,
|
|
329
|
+
body: T::Boolean,
|
|
330
|
+
started_at: Integer,
|
|
331
|
+
built_at: Integer
|
|
332
|
+
).returns(T.attached_class)
|
|
333
|
+
end
|
|
334
|
+
def self.new(scope, body:, started_at:, built_at:)
|
|
335
|
+
end
|
|
336
|
+
end
|
|
337
|
+
end
|
|
338
|
+
end
|
|
339
|
+
end
|
|
340
|
+
end
|