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.
Files changed (65) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +22 -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_params.rb +9 -1
  23. data/lib/turbopuffer/models/namespace_query_response.rb +10 -2
  24. data/lib/turbopuffer/models/namespace_recall_response.rb +5 -0
  25. data/lib/turbopuffer/models/namespace_start_copy_from_response.rb +2 -0
  26. data/lib/turbopuffer/models/namespace_write_params.rb +3 -3
  27. data/lib/turbopuffer/models/operation_error.rb +2 -0
  28. data/lib/turbopuffer/models/rerank_model_params.rb +38 -0
  29. data/lib/turbopuffer/models/write_result.rb +1 -1
  30. data/lib/turbopuffer/models.rb +2 -0
  31. data/lib/turbopuffer/resources/namespaces.rb +4 -2
  32. data/lib/turbopuffer/version.rb +1 -1
  33. data/lib/turbopuffer.rb +3 -0
  34. data/rbi/turbopuffer/client.rbi +5 -0
  35. data/rbi/turbopuffer/internal/telemetry.rbi +275 -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/namespace_hint_cache_warm_response.rbi +2 -0
  44. data/rbi/turbopuffer/models/namespace_metadata.rbi +5 -0
  45. data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
  46. data/rbi/turbopuffer/models/namespace_query_params.rbi +11 -0
  47. data/rbi/turbopuffer/models/namespace_query_response.rbi +8 -1
  48. data/rbi/turbopuffer/models/namespace_recall_response.rbi +4 -0
  49. data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi +1 -0
  50. data/rbi/turbopuffer/models/namespace_write_params.rbi +3 -3
  51. data/rbi/turbopuffer/models/operation_error.rbi +1 -0
  52. data/rbi/turbopuffer/models/rerank_model_params.rbi +48 -0
  53. data/rbi/turbopuffer/models/write_result.rbi +1 -1
  54. data/rbi/turbopuffer/models.rbi +2 -0
  55. data/rbi/turbopuffer/resources/namespaces.rbi +5 -1
  56. data/sig/turbopuffer/client.rbs +1 -0
  57. data/sig/turbopuffer/internal/telemetry.rbs +129 -0
  58. data/sig/turbopuffer/internal/transport/base_client.rbs +5 -1
  59. data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs +15 -1
  60. data/sig/turbopuffer/internal/transport/request_observer.rbs +153 -0
  61. data/sig/turbopuffer/models/namespace_query_params.rbs +9 -0
  62. data/sig/turbopuffer/models/rerank_model_params.rbs +18 -0
  63. data/sig/turbopuffer/models.rbs +2 -0
  64. data/sig/turbopuffer/resources/namespaces.rbs +1 -0
  65. 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