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
@@ -77,7 +77,7 @@ module Turbopuffer
77
77
  optional :encryption, union: -> { Turbopuffer::Encryption }
78
78
 
79
79
  # @!attribute patch_by_filter
80
- # The patch and filter specifying which documents to patch.
80
+ # Sets the attributes in `patch` on every document that matches `filters`.
81
81
  #
82
82
  # @return [Turbopuffer::Models::NamespaceWriteParams::PatchByFilter, nil]
83
83
  optional :patch_by_filter, -> { Turbopuffer::NamespaceWriteParams::PatchByFilter }
@@ -175,7 +175,7 @@ module Turbopuffer
175
175
  #
176
176
  # @param encryption [Turbopuffer::Models::Encryption::CustomerManaged, Turbopuffer::Models::Encryption::Default] The encryption configuration for a namespace.
177
177
  #
178
- # @param patch_by_filter [Turbopuffer::Models::NamespaceWriteParams::PatchByFilter] The patch and filter specifying which documents to patch.
178
+ # @param patch_by_filter [Turbopuffer::Models::NamespaceWriteParams::PatchByFilter] Sets the attributes in `patch` on every document that matches `filters`.
179
179
  #
180
180
  # @param patch_by_filter_allow_partial [Boolean] Allow partial completion when filter matches too many documents.
181
181
  #
@@ -212,7 +212,7 @@ module Turbopuffer
212
212
  required :patch, Turbopuffer::Internal::Type::HashOf[Turbopuffer::Internal::Type::Unknown]
213
213
 
214
214
  # @!method initialize(filters:, patch:)
215
- # The patch and filter specifying which documents to patch.
215
+ # Sets the attributes in `patch` on every document that matches `filters`.
216
216
  #
217
217
  # @param filters [Object] Filter by attributes. Same syntax as the query endpoint.
218
218
  #
@@ -16,6 +16,8 @@ module Turbopuffer
16
16
  required :status_code, Integer
17
17
 
18
18
  # @!method initialize(detail:, status_code:)
19
+ # The error of an asynchronous operation that failed.
20
+ #
19
21
  # @param detail [Turbopuffer::Models::OperationError::Detail] The response to an unsuccessful request.
20
22
  #
21
23
  # @param status_code [Integer] The HTTP status code of the operation's error.
@@ -82,7 +82,7 @@ module Turbopuffer
82
82
  # Some parameter documentations has been truncated, see
83
83
  # {Turbopuffer::Models::WriteResult} for more details.
84
84
  #
85
- # The response to a successful write request.
85
+ # The copy succeeded, with the result of its write.
86
86
  #
87
87
  # @param billing [Turbopuffer::Models::WriteBilling] The billing information for a write request.
88
88
  #
@@ -106,7 +106,7 @@ module Turbopuffer
106
106
  #
107
107
  # @param compute_attributes [Hash{Symbol=>Object}] Body param: Computes additional values on documents returned by a query. Each ke
108
108
  #
109
- # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency] Body param: The consistency level for a query.
109
+ # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
110
110
  #
111
111
  # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] Body param: A function used to calculate vector similarity.
112
112
  #
@@ -209,7 +209,7 @@ module Turbopuffer
209
209
  #
210
210
  # @param namespace [String] Path param: The name of the namespace.
211
211
  #
212
- # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency] Body param: The consistency level for a query.
212
+ # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
213
213
  #
214
214
  # @param limit [Integer, Turbopuffer::Models::RerankLimit] Body param: Limits the total number of reranked documents returned.
215
215
  #
@@ -279,7 +279,7 @@ module Turbopuffer
279
279
  #
280
280
  # @param compute_attributes [Hash{Symbol=>Object}] Body param: Computes additional values on documents returned by a query. Each ke
281
281
  #
282
- # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency] Body param: The consistency level for a query.
282
+ # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
283
283
  #
284
284
  # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] Body param: A function used to calculate vector similarity.
285
285
  #
@@ -516,7 +516,7 @@ module Turbopuffer
516
516
  #
517
517
  # @param encryption [Turbopuffer::Models::Encryption::CustomerManaged, Turbopuffer::Models::Encryption::Default] Body param: The encryption configuration for a namespace.
518
518
  #
519
- # @param patch_by_filter [Turbopuffer::Models::NamespaceWriteParams::PatchByFilter] Body param: The patch and filter specifying which documents to patch.
519
+ # @param patch_by_filter [Turbopuffer::Models::NamespaceWriteParams::PatchByFilter] Body param: Sets the attributes in `patch` on every document that matches `filte
520
520
  #
521
521
  # @param patch_by_filter_allow_partial [Boolean] Body param: Allow partial completion when filter matches too many documents.
522
522
  #
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Turbopuffer
4
- VERSION = "2.8.0"
4
+ VERSION = "2.10.0"
5
5
  end
data/lib/turbopuffer.rb CHANGED
@@ -49,9 +49,11 @@ require_relative "turbopuffer/internal"
49
49
  require_relative "turbopuffer/request_options"
50
50
  require_relative "turbopuffer/file_part"
51
51
  require_relative "turbopuffer/errors"
52
+ require_relative "turbopuffer/internal/transport/request_observer"
52
53
  require_relative "turbopuffer/internal/transport/base_client"
53
54
  require_relative "turbopuffer/internal/transport/pooled_net_requester"
54
55
  require_relative "turbopuffer/internal/respond_async"
56
+ require_relative "turbopuffer/internal/telemetry"
55
57
  require_relative "turbopuffer/client"
56
58
  require_relative "turbopuffer/internal/namespace_page"
57
59
  require_relative "turbopuffer/models/pinning_config"
@@ -66,6 +66,7 @@ module Turbopuffer
66
66
  default_namespace: T.nilable(String),
67
67
  base_url: T.nilable(String),
68
68
  compression: T::Boolean,
69
+ telemetry: T.nilable(T::Boolean),
69
70
  max_retries: Integer,
70
71
  timeout: Float,
71
72
  initial_retry_delay: Float,
@@ -83,6 +84,10 @@ module Turbopuffer
83
84
  base_url: ENV["TURBOPUFFER_BASE_URL"],
84
85
  # Whether to request compressed responses. Defaults to false.
85
86
  compression: false,
87
+ # Whether to report client-side request timings to turbopuffer on subsequent
88
+ # requests. Defaults to `ENV["TURBOPUFFER_TELEMETRY"]`, and is off when that's
89
+ # unset.
90
+ telemetry: nil,
86
91
  # Max number of retries to attempt after a failed retryable request.
87
92
  max_retries: Turbopuffer::Client::DEFAULT_MAX_RETRIES,
88
93
  timeout: Turbopuffer::Client::DEFAULT_TIMEOUT_IN_SECONDS,
@@ -0,0 +1,315 @@
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
+ # Sorted by ASCII value, so that encoded IDs sort like their bytes.
13
+ REQUEST_ID_ALPHABET = T.let(T.unsafe(nil), String)
14
+ # The bytes in a request ID before it's encoded.
15
+ REQUEST_ID_BYTES = T.let(T.unsafe(nil), Integer)
16
+ # The request header that carries the IDs of recorded requests.
17
+ REQUEST_ID_HEADER = T.let(T.unsafe(nil), String)
18
+ # The prefix of generated request IDs.
19
+ REQUEST_ID_PREFIX = T.let(T.unsafe(nil), String)
20
+ # The random bytes at the start of a request ID.
21
+ REQUEST_ID_RANDOM_BYTES = T.let(T.unsafe(nil), Integer)
22
+
23
+ ENVELOPE_VERSION = T.let(T.unsafe(nil), Integer)
24
+
25
+ MAX_RECORDS_PER_HEADER = T.let(T.unsafe(nil), Integer)
26
+ MAX_BUFFERED_RECORDS = T.let(T.unsafe(nil), Integer)
27
+
28
+ TRUE_VALUES = T.let(T.unsafe(nil), T::Array[String])
29
+ FALSE_VALUES = T.let(T.unsafe(nil), T::Array[String])
30
+
31
+ NAMESPACE_RE = T.let(T.unsafe(nil), Regexp)
32
+ OPERATION_RE = T.let(T.unsafe(nil), Regexp)
33
+ SCHEME_AND_HOST_RE = T.let(T.unsafe(nil), Regexp)
34
+
35
+ class << self
36
+ # @api private
37
+ #
38
+ # Resolves whether telemetry is enabled, preferring an explicit value over the environment.
39
+ sig { params(value: T.nilable(T::Boolean)).returns(T::Boolean) }
40
+ def resolve_enabled(value)
41
+ end
42
+
43
+ # @api private
44
+ #
45
+ # Returns the method and path of a request with identifiers like the namespace replaced.
46
+ sig do
47
+ params(
48
+ method: T.any(Symbol, String),
49
+ url: T.any(URI::Generic, String)
50
+ ).returns(String)
51
+ end
52
+ def route_template(method, url)
53
+ end
54
+
55
+ # @api private
56
+ #
57
+ # Returns the duration in nanoseconds of each client-side phase of an attempt ending at
58
+ # `end_at`. Phases that weren't observed are left out.
59
+ sig do
60
+ params(
61
+ timings: Turbopuffer::Internal::Transport::RequestObserver::Timings,
62
+ end_at: Integer
63
+ ).returns(T::Hash[Symbol, Integer])
64
+ end
65
+ def compute_durations(timings, end_at)
66
+ end
67
+
68
+ # @api private
69
+ sig { returns(Float) }
70
+ def random
71
+ end
72
+
73
+ # @api private
74
+ #
75
+ # Encodes `bytes` in base32 with `REQUEST_ID_ALPHABET`, in RFC 4648's bit order without
76
+ # padding.
77
+ sig { params(bytes: String).returns(String) }
78
+ def encode_base32(bytes)
79
+ end
80
+
81
+ # @api private
82
+ #
83
+ # Generates the ID of a request that will be recorded. Its format is private to turbopuffer.
84
+ sig { params(now: Time, random: String).returns(String) }
85
+ def new_request_id(
86
+ now,
87
+ random: SecureRandom.random_bytes(REQUEST_ID_RANDOM_BYTES)
88
+ )
89
+ end
90
+
91
+ # @api private
92
+ #
93
+ # Returns the buffer shared by clients with the same API key and base URL, or nil if
94
+ # telemetry is disabled.
95
+ sig do
96
+ params(
97
+ enabled: T.nilable(T::Boolean),
98
+ api_key: String,
99
+ base_url: String
100
+ ).returns(T.nilable(Turbopuffer::Internal::Telemetry::Buffer))
101
+ end
102
+ def buffer_for(enabled, api_key, base_url)
103
+ end
104
+
105
+ # @api private
106
+ sig { void }
107
+ def after_fork_in_child
108
+ end
109
+
110
+ sig { void }
111
+ private def install_fork_hook
112
+ end
113
+ end
114
+
115
+ # @api private
116
+ #
117
+ # Records taken from a buffer, encoded as a header value.
118
+ class Batch
119
+ sig { returns(T::Array[[Integer, T::Hash[Symbol, T.anything]]]) }
120
+ attr_reader :records
121
+
122
+ sig { returns(Integer) }
123
+ attr_reader :dropped
124
+
125
+ sig { returns(String) }
126
+ attr_reader :header
127
+
128
+ # @api private
129
+ sig do
130
+ params(
131
+ records: T::Array[[Integer, T::Hash[Symbol, T.anything]]],
132
+ dropped: Integer
133
+ ).returns(T.attached_class)
134
+ end
135
+ def self.new(records, dropped)
136
+ end
137
+ end
138
+
139
+ # @api private
140
+ #
141
+ # Buffers per-request telemetry records until a later request can carry them.
142
+ class Buffer
143
+ sig { returns(Float) }
144
+ attr_reader :sample_rate
145
+
146
+ # @api private
147
+ sig { returns(T.attached_class) }
148
+ def self.new
149
+ end
150
+
151
+ # @api private
152
+ #
153
+ # Adopts the sample rate advertised by the server, ignoring invalid values.
154
+ sig { params(response: Net::HTTPResponse).void }
155
+ def observe_response(response)
156
+ end
157
+
158
+ # @api private
159
+ #
160
+ # Decides whether to record a request that's starting, returning the sample rate it was
161
+ # recorded at.
162
+ sig { returns(T.nilable(Float)) }
163
+ def sample
164
+ end
165
+
166
+ # @api private
167
+ #
168
+ # Buffers the record of a request sampled at `sample_rate`.
169
+ sig do
170
+ params(
171
+ method: T.any(Symbol, String),
172
+ url: T.any(URI::Generic, String),
173
+ status: Integer,
174
+ retries: Integer,
175
+ durations: T::Hash[Symbol, Integer],
176
+ sample_rate: Float,
177
+ server_total_ms: T.nilable(Numeric),
178
+ error: T.nilable(String),
179
+ reused: T.nilable(T::Boolean),
180
+ request_id: T.nilable(String)
181
+ ).void
182
+ end
183
+ def record(
184
+ method:,
185
+ url:,
186
+ status:,
187
+ retries:,
188
+ durations:,
189
+ sample_rate:,
190
+ server_total_ms: nil,
191
+ error: nil,
192
+ reused: nil,
193
+ request_id: nil
194
+ )
195
+ end
196
+
197
+ # @api private
198
+ #
199
+ # Removes up to `MAX_RECORDS_PER_HEADER` of the oldest records.
200
+ sig { returns(T.nilable(Turbopuffer::Internal::Telemetry::Batch)) }
201
+ def take
202
+ end
203
+
204
+ # @api private
205
+ #
206
+ # Returns a batch that never reached the server to the front of the buffer.
207
+ sig { params(batch: Turbopuffer::Internal::Telemetry::Batch).void }
208
+ def restore(batch)
209
+ end
210
+
211
+ # @api private
212
+ sig { void }
213
+ def reset_after_fork
214
+ end
215
+ end
216
+
217
+ # @api private
218
+ #
219
+ # Installs the request observer that records telemetry for a client.
220
+ class Observer < Turbopuffer::Internal::Transport::RequestObserver
221
+ sig { returns(Turbopuffer::Internal::Telemetry::Buffer) }
222
+ attr_reader :buffer
223
+
224
+ # @api private
225
+ sig do
226
+ params(buffer: Turbopuffer::Internal::Telemetry::Buffer).returns(
227
+ T.attached_class
228
+ )
229
+ end
230
+ def self.new(buffer)
231
+ end
232
+
233
+ # @api private
234
+ sig do
235
+ params(
236
+ info: Turbopuffer::Internal::Transport::RequestObserver::RequestInfo
237
+ ).returns(Turbopuffer::Internal::Telemetry::Scope)
238
+ end
239
+ def start(info)
240
+ end
241
+ end
242
+
243
+ # @api private
244
+ class Scope < Turbopuffer::Internal::Transport::RequestObserver::RequestScope
245
+ # @api private
246
+ sig do
247
+ params(
248
+ buffer: Turbopuffer::Internal::Telemetry::Buffer,
249
+ info: Turbopuffer::Internal::Transport::RequestObserver::RequestInfo
250
+ ).returns(T.attached_class)
251
+ end
252
+ def self.new(buffer, info)
253
+ end
254
+
255
+ # @api private
256
+ sig do
257
+ params(attempt: Integer, request: T::Hash[Symbol, T.anything]).void
258
+ end
259
+ def attempt_begin(attempt, request)
260
+ end
261
+
262
+ # @api private
263
+ sig do
264
+ params(
265
+ result:
266
+ Turbopuffer::Internal::Transport::RequestObserver::AttemptResult
267
+ ).void
268
+ end
269
+ def attempt_end(result)
270
+ end
271
+
272
+ # @api private
273
+ sig do
274
+ params(
275
+ result:
276
+ Turbopuffer::Internal::Transport::RequestObserver::RequestResult
277
+ ).void
278
+ end
279
+ def finish(result)
280
+ end
281
+
282
+ sig do
283
+ params(
284
+ result:
285
+ Turbopuffer::Internal::Transport::RequestObserver::RequestResult
286
+ ).returns(Integer)
287
+ end
288
+ private def status(result)
289
+ end
290
+
291
+ sig { params(kind: T.nilable(Symbol)).returns(T.nilable(String)) }
292
+ private def error_name(kind)
293
+ end
294
+
295
+ sig { params(parsed: T.anything).returns(T.nilable(Numeric)) }
296
+ private def server_total_ms(parsed)
297
+ end
298
+
299
+ sig { params(value: T.anything, name: Symbol).returns(T.anything) }
300
+ private def field(value, name)
301
+ end
302
+ end
303
+
304
+ # @api private
305
+ #
306
+ # Resets telemetry in forked children.
307
+ module ForkHook
308
+ # @api private
309
+ sig { returns(Integer) }
310
+ def _fork
311
+ end
312
+ end
313
+ end
314
+ end
315
+ 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(