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
@@ -27,6 +27,7 @@ module Turbopuffer
27
27
  sig { returns(String) }
28
28
  attr_accessor :source_namespace
29
29
 
30
+ # Configuration for branching from another namespace.
30
31
  sig { params(source_namespace: String).returns(T.attached_class) }
31
32
  def self.new(
32
33
  # The namespace to create an instant, copy-on-write clone of.
@@ -38,6 +38,7 @@ module Turbopuffer
38
38
  sig { params(progress: String).void }
39
39
  attr_writer :progress
40
40
 
41
+ # The copy is still in progress.
41
42
  sig do
42
43
  params(start_time: Time, progress: String, status: Symbol).returns(
43
44
  T.attached_class
@@ -75,6 +76,7 @@ module Turbopuffer
75
76
  sig { returns(Time) }
76
77
  attr_accessor :finish_time
77
78
 
79
+ # The result of the copy.
78
80
  sig { returns(Turbopuffer::CopyFromNamespaceOperationResult::Variants) }
79
81
  attr_accessor :result
80
82
 
@@ -85,6 +87,7 @@ module Turbopuffer
85
87
  sig { returns(Symbol) }
86
88
  attr_accessor :status
87
89
 
90
+ # The copy has finished, successfully or not.
88
91
  sig do
89
92
  params(
90
93
  finish_time: Time,
@@ -100,6 +103,7 @@ module Turbopuffer
100
103
  def self.new(
101
104
  # The time at which the operation finished.
102
105
  finish_time:,
106
+ # The result of the copy.
103
107
  result:,
104
108
  # The time at which the operation started.
105
109
  start_time:,
@@ -2,6 +2,7 @@
2
2
 
3
3
  module Turbopuffer
4
4
  module Models
5
+ # The result of a finished copy operation.
5
6
  module CopyFromNamespaceOperationResult
6
7
  extend Turbopuffer::Internal::Type::Union
7
8
 
@@ -22,7 +23,7 @@ module Turbopuffer
22
23
  )
23
24
  end
24
25
 
25
- # The response to a successful write request.
26
+ # The copy succeeded, with the result of its write.
26
27
  sig { returns(Turbopuffer::WriteResult) }
27
28
  attr_reader :success
28
29
 
@@ -35,7 +36,7 @@ module Turbopuffer
35
36
  )
36
37
  end
37
38
  def self.new(
38
- # The response to a successful write request.
39
+ # The copy succeeded, with the result of its write.
39
40
  success:
40
41
  )
41
42
  end
@@ -54,6 +55,7 @@ module Turbopuffer
54
55
  )
55
56
  end
56
57
 
58
+ # The copy failed, with its error.
57
59
  sig { returns(Turbopuffer::OperationError) }
58
60
  attr_reader :error
59
61
 
@@ -65,7 +67,10 @@ module Turbopuffer
65
67
  T.attached_class
66
68
  )
67
69
  end
68
- def self.new(error:)
70
+ def self.new(
71
+ # The copy failed, with its error.
72
+ error:
73
+ )
69
74
  end
70
75
 
71
76
  sig { override.returns({ error: Turbopuffer::OperationError }) }
@@ -41,6 +41,7 @@ module Turbopuffer
41
41
  sig { params(source_region: String).void }
42
42
  attr_writer :source_region
43
43
 
44
+ # Configuration for copying documents from another namespace.
44
45
  sig do
45
46
  params(
46
47
  source_namespace: String,
@@ -15,6 +15,7 @@ module Turbopuffer
15
15
  sig { returns(Symbol) }
16
16
  attr_accessor :status
17
17
 
18
+ # A message describing the result of the request.
18
19
  sig { returns(T.nilable(String)) }
19
20
  attr_reader :message
20
21
 
@@ -24,6 +25,7 @@ module Turbopuffer
24
25
  # The response to a successful cache warm request.
25
26
  sig { params(message: String, status: Symbol).returns(T.attached_class) }
26
27
  def self.new(
28
+ # A message describing the result of the request.
27
29
  message: nil,
28
30
  # The status of the request.
29
31
  status: :ACCEPTED
@@ -24,6 +24,7 @@ module Turbopuffer
24
24
  sig { returns(Turbopuffer::Encryption::Variants) }
25
25
  attr_accessor :encryption
26
26
 
27
+ # The state of the namespace's index.
27
28
  sig { returns(Turbopuffer::NamespaceMetadata::Index::Variants) }
28
29
  attr_accessor :index
29
30
 
@@ -94,6 +95,7 @@ module Turbopuffer
94
95
  created_at:,
95
96
  # The encryption configuration for a namespace.
96
97
  encryption:,
98
+ # The state of the namespace's index.
97
99
  index:,
98
100
  # The schema of the namespace.
99
101
  schema:,
@@ -131,6 +133,7 @@ module Turbopuffer
131
133
  def to_hash
132
134
  end
133
135
 
136
+ # The state of the namespace's index.
134
137
  module Index
135
138
  extend Turbopuffer::Internal::Type::Union
136
139
 
@@ -154,6 +157,7 @@ module Turbopuffer
154
157
  sig { returns(Symbol) }
155
158
  attr_accessor :status
156
159
 
160
+ # Every document in the namespace is indexed.
157
161
  sig { params(status: Symbol).returns(T.attached_class) }
158
162
  def self.new(status: :"up-to-date")
159
163
  end
@@ -184,6 +188,7 @@ module Turbopuffer
184
188
  sig { returns(Integer) }
185
189
  attr_accessor :unindexed_rows
186
190
 
191
+ # Some documents are in the write-ahead log and haven't been indexed yet.
187
192
  sig do
188
193
  params(
189
194
  unindexed_bytes: Integer,
@@ -25,6 +25,8 @@ module Turbopuffer
25
25
  sig { params(performance: Turbopuffer::QueryPerformance::OrHash).void }
26
26
  attr_writer :performance
27
27
 
28
+ # The results of each subquery, in the same order as `queries`. With `rerank_by`,
29
+ # a single result combining the subqueries' rows.
28
30
  sig do
29
31
  returns(
30
32
  T::Array[Turbopuffer::Models::NamespaceMultiQueryResponse::Result]
@@ -48,6 +50,8 @@ module Turbopuffer
48
50
  billing:,
49
51
  # The performance information for a query.
50
52
  performance:,
53
+ # The results of each subquery, in the same order as `queries`. With `rerank_by`,
54
+ # a single result combining the subqueries' rows.
51
55
  results:
52
56
  )
53
57
  end
@@ -88,12 +92,18 @@ module Turbopuffer
88
92
  sig { params(aggregations: T::Hash[Symbol, T.anything]).void }
89
93
  attr_writer :aggregations
90
94
 
95
+ # The documents that matched the query, ordered by `rank_by`. Only present when
96
+ # `rank_by` is set.
91
97
  sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
92
98
  attr_reader :rows
93
99
 
94
100
  sig { params(rows: T::Array[Turbopuffer::Row::OrHash]).void }
95
101
  attr_writer :rows
96
102
 
103
+ # The result of a query, or of one subquery of a multi-query. With `aggregate_by`,
104
+ # `aggregations` maps each aggregation's label to its value. With `group_by` as
105
+ # well, `aggregation_groups` holds one object per group instead, with its group
106
+ # key and the value of each aggregation.
97
107
  sig do
98
108
  params(
99
109
  aggregation_groups: T::Array[T::Hash[Symbol, T.anything]],
@@ -101,7 +111,13 @@ module Turbopuffer
101
111
  rows: T::Array[Turbopuffer::Row::OrHash]
102
112
  ).returns(T.attached_class)
103
113
  end
104
- def self.new(aggregation_groups: nil, aggregations: nil, rows: nil)
114
+ def self.new(
115
+ aggregation_groups: nil,
116
+ aggregations: nil,
117
+ # The documents that matched the query, ordered by `rank_by`. Only present when
118
+ # `rank_by` is set.
119
+ rows: nil
120
+ )
105
121
  end
106
122
 
107
123
  sig do
@@ -114,6 +114,13 @@ module Turbopuffer
114
114
  sig { params(rank_by: T.anything).void }
115
115
  attr_writer :rank_by
116
116
 
117
+ # Rerank retrieved candidates with a model.
118
+ sig { returns(T.nilable(Turbopuffer::RerankModelParams)) }
119
+ attr_reader :rerank_by
120
+
121
+ sig { params(rerank_by: Turbopuffer::RerankModelParams::OrHash).void }
122
+ attr_writer :rerank_by
123
+
117
124
  # The number of results to return.
118
125
  sig { returns(T.nilable(Integer)) }
119
126
  attr_reader :top_k
@@ -144,6 +151,7 @@ module Turbopuffer
144
151
  limit: T.any(Integer, Turbopuffer::Limit::OrHash),
145
152
  offset: Integer,
146
153
  rank_by: T.anything,
154
+ rerank_by: Turbopuffer::RerankModelParams::OrHash,
147
155
  top_k: Integer,
148
156
  vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
149
157
  request_options: Turbopuffer::RequestOptions::OrHash
@@ -180,6 +188,8 @@ module Turbopuffer
180
188
  offset: nil,
181
189
  # How to rank the documents in the namespace.
182
190
  rank_by: nil,
191
+ # Rerank retrieved candidates with a model.
192
+ rerank_by: nil,
183
193
  # The number of results to return.
184
194
  top_k: nil,
185
195
  # The encoding to use for vectors in the response.
@@ -203,6 +213,7 @@ module Turbopuffer
203
213
  limit: T.any(Integer, Turbopuffer::Limit),
204
214
  offset: Integer,
205
215
  rank_by: T.anything,
216
+ rerank_by: Turbopuffer::RerankModelParams,
206
217
  top_k: Integer,
207
218
  vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
208
219
  request_options: Turbopuffer::RequestOptions
@@ -39,13 +39,18 @@ module Turbopuffer
39
39
  sig { params(aggregations: T::Hash[Symbol, T.anything]).void }
40
40
  attr_writer :aggregations
41
41
 
42
+ # The documents that matched the query, ordered by `rank_by`. Only present when
43
+ # `rank_by` is set.
42
44
  sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
43
45
  attr_reader :rows
44
46
 
45
47
  sig { params(rows: T::Array[Turbopuffer::Row::OrHash]).void }
46
48
  attr_writer :rows
47
49
 
48
- # The result of a query.
50
+ # The result of a query. With `aggregate_by`, `aggregations` maps each
51
+ # aggregation's label to its value. With `group_by` as well, `aggregation_groups`
52
+ # holds one object per group instead, with its group key and the value of each
53
+ # aggregation.
49
54
  sig do
50
55
  params(
51
56
  billing: Turbopuffer::QueryBilling::OrHash,
@@ -62,6 +67,8 @@ module Turbopuffer
62
67
  performance:,
63
68
  aggregation_groups: nil,
64
69
  aggregations: nil,
70
+ # The documents that matched the query, ordered by `rank_by`. Only present when
71
+ # `rank_by` is set.
65
72
  rows: nil
66
73
  )
67
74
  end
@@ -104,6 +104,10 @@ module Turbopuffer
104
104
  sig { returns(T::Array[Float]) }
105
105
  attr_accessor :query_vector
106
106
 
107
+ # One of the searches the evaluation ran: its query vector, sampled at random from
108
+ # the namespace's vectors unless `rank_by` is set, and the query's true nearest
109
+ # neighbors, found by exhaustive search. Recall compares these neighbors to the
110
+ # results of the approximate nearest neighbor (ANN) search.
107
111
  sig do
108
112
  params(
109
113
  nearest_neighbors: T::Array[Turbopuffer::Row::OrHash],
@@ -15,6 +15,7 @@ module Turbopuffer
15
15
  sig { returns(String) }
16
16
  attr_accessor :token
17
17
 
18
+ # The response to a successful request to start a copy.
18
19
  sig { params(token: String).returns(T.attached_class) }
19
20
  def self.new(
20
21
  # The token identifying the copy operation.
@@ -147,7 +147,7 @@ module Turbopuffer
147
147
  end
148
148
  attr_writer :encryption
149
149
 
150
- # The patch and filter specifying which documents to patch.
150
+ # Sets the attributes in `patch` on every document that matches `filters`.
151
151
  sig do
152
152
  returns(T.nilable(Turbopuffer::NamespaceWriteParams::PatchByFilter))
153
153
  end
@@ -337,7 +337,7 @@ module Turbopuffer
337
337
  distance_metric: nil,
338
338
  # The encryption configuration for a namespace.
339
339
  encryption: nil,
340
- # The patch and filter specifying which documents to patch.
340
+ # Sets the attributes in `patch` on every document that matches `filters`.
341
341
  patch_by_filter: nil,
342
342
  # Allow partial completion when filter matches too many documents.
343
343
  patch_by_filter_allow_partial: nil,
@@ -438,7 +438,7 @@ module Turbopuffer
438
438
  sig { returns(T::Hash[Symbol, T.anything]) }
439
439
  attr_accessor :patch
440
440
 
441
- # The patch and filter specifying which documents to patch.
441
+ # Sets the attributes in `patch` on every document that matches `filters`.
442
442
  sig do
443
443
  params(
444
444
  filters: T.anything,
@@ -19,6 +19,7 @@ module Turbopuffer
19
19
  sig { returns(Integer) }
20
20
  attr_accessor :status_code
21
21
 
22
+ # The error of an asynchronous operation that failed.
22
23
  sig do
23
24
  params(
24
25
  detail: Turbopuffer::OperationError::Detail::OrHash,
@@ -0,0 +1,48 @@
1
+ # typed: strong
2
+
3
+ module Turbopuffer
4
+ module Models
5
+ class RerankModelParams < Turbopuffer::Internal::Type::BaseModel
6
+ OrHash =
7
+ T.type_alias do
8
+ T.any(Turbopuffer::RerankModelParams, Turbopuffer::Internal::AnyHash)
9
+ end
10
+
11
+ # The string attribute to score. Must be included in `include_attributes` in every
12
+ # query.
13
+ sig { returns(String) }
14
+ attr_accessor :attribute
15
+
16
+ # Which reranking model to use.
17
+ sig { returns(String) }
18
+ attr_accessor :model
19
+
20
+ # The query text to score each document against.
21
+ sig { returns(String) }
22
+ attr_accessor :query
23
+
24
+ # Rerank retrieved candidates with a model.
25
+ sig do
26
+ params(attribute: String, model: String, query: String).returns(
27
+ T.attached_class
28
+ )
29
+ end
30
+ def self.new(
31
+ # The string attribute to score. Must be included in `include_attributes` in every
32
+ # query.
33
+ attribute:,
34
+ # Which reranking model to use.
35
+ model:,
36
+ # The query text to score each document against.
37
+ query:
38
+ )
39
+ end
40
+
41
+ sig do
42
+ override.returns({ attribute: String, model: String, query: String })
43
+ end
44
+ def to_hash
45
+ end
46
+ end
47
+ end
48
+ end
@@ -86,7 +86,7 @@ module Turbopuffer
86
86
  sig { params(upserted_ids: T::Array[Turbopuffer::ID::Variants]).void }
87
87
  attr_writer :upserted_ids
88
88
 
89
- # The response to a successful write request.
89
+ # The copy succeeded, with the result of its write.
90
90
  sig do
91
91
  params(
92
92
  billing: Turbopuffer::WriteBilling::OrHash,
@@ -119,6 +119,8 @@ module Turbopuffer
119
119
 
120
120
  RerankLimit = Turbopuffer::Models::RerankLimit
121
121
 
122
+ RerankModelParams = Turbopuffer::Models::RerankModelParams
123
+
122
124
  Row = Turbopuffer::Models::Row
123
125
 
124
126
  RrfParams = Turbopuffer::Models::RrfParams
@@ -223,6 +223,7 @@ module Turbopuffer
223
223
  limit: T.any(Integer, Turbopuffer::Limit::OrHash),
224
224
  offset: Integer,
225
225
  rank_by: T.anything,
226
+ rerank_by: Turbopuffer::RerankModelParams::OrHash,
226
227
  top_k: Integer,
227
228
  vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
228
229
  request_options: Turbopuffer::RequestOptions::OrHash
@@ -260,6 +261,8 @@ module Turbopuffer
260
261
  offset: nil,
261
262
  # Body param: How to rank the documents in the namespace.
262
263
  rank_by: nil,
264
+ # Body param: Rerank retrieved candidates with a model.
265
+ rerank_by: nil,
263
266
  # Body param: The number of results to return.
264
267
  top_k: nil,
265
268
  # Body param: The encoding to use for vectors in the response.
@@ -478,7 +481,8 @@ module Turbopuffer
478
481
  distance_metric: nil,
479
482
  # Body param: The encryption configuration for a namespace.
480
483
  encryption: nil,
481
- # Body param: The patch and filter specifying which documents to patch.
484
+ # Body param: Sets the attributes in `patch` on every document that matches
485
+ # `filters`.
482
486
  patch_by_filter: nil,
483
487
  # Body param: Allow partial completion when filter matches too many documents.
484
488
  patch_by_filter_allow_partial: nil,
@@ -33,6 +33,7 @@ module Turbopuffer
33
33
  ?default_namespace: String?,
34
34
  ?base_url: String?,
35
35
  ?compression: bool,
36
+ ?telemetry: bool?,
36
37
  ?max_retries: Integer,
37
38
  ?timeout: Float,
38
39
  ?initial_retry_delay: Float,
@@ -0,0 +1,129 @@
1
+ module Turbopuffer
2
+ module Internal
3
+ module Telemetry
4
+ ENV_VAR: String
5
+ HEADER: String
6
+ SAMPLE_RATE_HEADER: String
7
+
8
+ ENVELOPE_VERSION: Integer
9
+
10
+ MAX_RECORDS_PER_HEADER: Integer
11
+ MAX_BUFFERED_RECORDS: Integer
12
+
13
+ TRUE_VALUES: ::Array[String]
14
+ FALSE_VALUES: ::Array[String]
15
+
16
+ NAMESPACE_RE: Regexp
17
+ OPERATION_RE: Regexp
18
+ SCHEME_AND_HOST_RE: Regexp
19
+
20
+ def self.resolve_enabled: (bool? value) -> bool
21
+
22
+ def self.route_template: (
23
+ Symbol | String method,
24
+ URI::Generic | String url
25
+ ) -> String
26
+
27
+ def self.compute_durations: (
28
+ Turbopuffer::Internal::Transport::RequestObserver::Timings timings,
29
+ Integer end_at
30
+ ) -> ::Hash[Symbol, Integer]
31
+
32
+ def self.random: -> Float
33
+
34
+ def self.buffer_for: (
35
+ bool? enabled,
36
+ String api_key,
37
+ String base_url
38
+ ) -> Turbopuffer::Internal::Telemetry::Buffer?
39
+
40
+ def self.after_fork_in_child: -> void
41
+
42
+ private def self.install_fork_hook: -> void
43
+
44
+ class Batch
45
+ attr_reader records: ::Array[[Integer, ::Hash[Symbol, top]]]
46
+
47
+ attr_reader dropped: Integer
48
+
49
+ attr_reader header: String
50
+
51
+ def initialize: (
52
+ ::Array[[Integer, ::Hash[Symbol, top]]] records,
53
+ Integer dropped
54
+ ) -> void
55
+ end
56
+
57
+ class Buffer
58
+ attr_reader sample_rate: Float
59
+
60
+ def initialize: -> void
61
+
62
+ def observe_response: (top response) -> void
63
+
64
+ def record: (
65
+ method: Symbol | String,
66
+ url: URI::Generic | String,
67
+ status: Integer,
68
+ retries: Integer,
69
+ durations: ::Hash[Symbol, Integer],
70
+ ?server_total_ms: Numeric?,
71
+ ?error: String?,
72
+ ?reused: bool?
73
+ ) -> void
74
+
75
+ def take: -> Turbopuffer::Internal::Telemetry::Batch?
76
+
77
+ def restore: (Turbopuffer::Internal::Telemetry::Batch batch) -> void
78
+
79
+ def reset_after_fork: -> void
80
+ end
81
+
82
+ class Observer < Turbopuffer::Internal::Transport::RequestObserver
83
+ attr_reader buffer: Turbopuffer::Internal::Telemetry::Buffer
84
+
85
+ def initialize: (
86
+ Turbopuffer::Internal::Telemetry::Buffer buffer
87
+ ) -> void
88
+
89
+ def start: (
90
+ Turbopuffer::Internal::Transport::RequestObserver::RequestInfo info
91
+ ) -> Turbopuffer::Internal::Telemetry::Scope
92
+ end
93
+
94
+ class Scope < Turbopuffer::Internal::Transport::RequestObserver::RequestScope
95
+ def initialize: (
96
+ Turbopuffer::Internal::Telemetry::Buffer buffer,
97
+ Turbopuffer::Internal::Transport::RequestObserver::RequestInfo info
98
+ ) -> void
99
+
100
+ def attempt_begin: (
101
+ Integer attempt,
102
+ ::Hash[Symbol, top] request
103
+ ) -> void
104
+
105
+ def attempt_end: (
106
+ Turbopuffer::Internal::Transport::RequestObserver::AttemptResult result
107
+ ) -> void
108
+
109
+ def finish: (
110
+ Turbopuffer::Internal::Transport::RequestObserver::RequestResult result
111
+ ) -> void
112
+
113
+ private def status: (
114
+ Turbopuffer::Internal::Transport::RequestObserver::RequestResult result
115
+ ) -> Integer
116
+
117
+ private def error_name: (Symbol? kind) -> String?
118
+
119
+ private def server_total_ms: (top parsed) -> Numeric?
120
+
121
+ private def field: (top value, Symbol name) -> top
122
+ end
123
+
124
+ module ForkHook
125
+ def _fork: -> Integer
126
+ end
127
+ end
128
+ end
129
+ end
@@ -73,6 +73,9 @@ module Turbopuffer
73
73
  # @api private
74
74
  attr_reader requester: Turbopuffer::Internal::Transport::PooledNetRequester
75
75
 
76
+ # @api private
77
+ attr_accessor request_observer: Turbopuffer::Internal::Transport::RequestObserver?
78
+
76
79
  def initialize: (
77
80
  base_url: String,
78
81
  ?timeout: Float,
@@ -105,7 +108,8 @@ module Turbopuffer
105
108
  Turbopuffer::Internal::Transport::BaseClient::request_input request,
106
109
  redirect_count: Integer,
107
110
  retry_count: Integer,
108
- send_retry_header: bool
111
+ send_retry_header: bool,
112
+ ?observation: Turbopuffer::Internal::Transport::RequestObserver::Observation?
109
113
  ) -> [Integer, top, Enumerable[String]]
110
114
 
111
115
  def request: (
@@ -10,13 +10,22 @@ module Turbopuffer
10
10
  url: URI::Generic,
11
11
  headers: ::Hash[String, String],
12
12
  body: top,
13
- deadline: Float
13
+ deadline: Float,
14
+ timings: Turbopuffer::Internal::Transport::RequestObserver::Timings?
14
15
  }
15
16
 
16
17
  KEEP_ALIVE_TIMEOUT: 30
17
18
 
18
19
  DEFAULT_MAX_CONNECTIONS: Integer
19
20
 
21
+ module ObservedConnection
22
+ attr_accessor request_timings: Turbopuffer::Internal::Transport::RequestObserver::Timings?
23
+ end
24
+
25
+ class ObservedRequest
26
+ attr_accessor request_timings: Turbopuffer::Internal::Transport::RequestObserver::Timings?
27
+ end
28
+
20
29
  def self.connect: (
21
30
  cert_store: OpenSSL::X509::Store,
22
31
  url: URI::Generic
@@ -24,6 +33,11 @@ module Turbopuffer
24
33
 
25
34
  def self.calibrate_socket_timeout: (top conn, Float deadline) -> void
26
35
 
36
+ def self.observe_connection: (
37
+ top conn,
38
+ Turbopuffer::Internal::Transport::RequestObserver::Timings? timings
39
+ ) -> void
40
+
27
41
  def self.build_request: (
28
42
  Turbopuffer::Internal::Transport::PooledNetRequester::request request
29
43
  ) {