xet_runtime/config/groups/client.rs
1use std::time::Duration;
2
3use crate::utils::ByteSize;
4
5crate::config_group!({
6
7 /// Retry at most this many times before permanently failing.
8 ///
9 /// The default value is 5.
10 ///
11 /// Use the environment variable `HF_XET_CLIENT_RETRY_MAX_ATTEMPTS` to set this value.
12 ref retry_max_attempts : usize = 5;
13
14 /// On errors that can be retried, delay for this amount of time
15 /// before retrying.
16 ///
17 /// The default value is 3sec.
18 ///
19 /// Use the environment variable `HF_XET_CLIENT_RETRY_BASE_DELAY` to set this value.
20 ref retry_base_delay : Duration = Duration::from_millis(3000);
21
22 /// Cap each individual retry sleep at this duration.
23 ///
24 /// Applied as the per-attempt maximum backoff delay. Retries continue until
25 /// `retry_max_attempts` is exhausted; the total time spent sleeping across
26 /// retries may exceed this value.
27 ///
28 /// The default value is 6min.
29 ///
30 /// Use the environment variable `HF_XET_CLIENT_RETRY_MAX_DURATION` to set this value.
31 ref retry_max_duration: Duration = Duration::from_secs(6 * 60);
32
33 /// Cleanup idle connections that are unused for this amount of time.
34 ///
35 /// The default value is 60sec.
36 ///
37 /// Use the environment variable `HF_XET_CLIENT_IDLE_CONNECTION_TIMEOUT` to set this value.
38 ref idle_connection_timeout: Duration = Duration::from_secs(60);
39
40 /// Only no more than this number of idle connections in the connection pool.
41 ///
42 /// The default value is 16.
43 ///
44 /// Use the environment variable `HF_XET_CLIENT_MAX_IDLE_CONNECTIONS` to set this value.
45 ref max_idle_connections: usize = 16;
46
47 /// Maximum time allowed to establish a TCP connection to the server.
48 /// This timeout applies only to connection establishment, not to data transfer.
49 ///
50 /// The default value is 60 seconds.
51 ///
52 /// Use the environment variable `HF_XET_CLIENT_CONNECT_TIMEOUT` to set this value.
53 ref connect_timeout: Duration = Duration::from_secs(60);
54
55 /// Maximum time allowed between receiving data packets during a transfer.
56 /// This timeout resets whenever data is received, allowing slow but progressing
57 /// transfers to complete. If no data is received for this duration, the connection
58 /// is considered stalled and will timeout.
59 ///
60 /// The default value is 300 seconds.
61 ///
62 /// Use the environment variable `HF_XET_CLIENT_READ_TIMEOUT` to set this value.
63 ref read_timeout: Duration = Duration::from_secs(300);
64
65 /// Send a report of a successful partial upload every 512kb.
66 ///
67 /// The default value is 524288.
68 ///
69 /// Use the environment variable `HF_XET_CLIENT_UPLOAD_REPORTING_BLOCK_SIZE` to set this value.
70 ref upload_reporting_block_size : usize = 512 * 1024;
71
72 /// Whether or not to enable the adaptive concurrency control.
73 ///
74 /// The default value is true.
75 ///
76 /// Use the environment variable `HF_XET_CLIENT_ENABLE_ADAPTIVE_CONCURRENCY` to set this value.
77 ref enable_adaptive_concurrency: bool = true;
78
79 /// The minimum time in milliseconds between adjustments when increasing the concurrency.
80 ///
81 /// The default value is 500ms.
82 ///
83 /// Use the environment variable `HF_XET_CLIENT_AC_MIN_ADJUSTMENT_WINDOW_MS` to set this value.
84 ref ac_min_adjustment_window_ms: u64 = 500;
85
86 /// The minimum number of bytes that must be observed before we start adjusting the concurrency. This,
87 /// along with ac_num_transmissions_required_for_adjustment, ensure that we have enough data points to
88 /// accurately predict the RTT. When these are too low, we observe that we can scale up the concurrency too quickly,
89 /// causing a burst of failed connections at the start of a transfer.
90 ///
91 /// The default value is 20mb.
92 ///
93 /// Use the environment variable `HF_XET_CLIENT_AC_MIN_BYTES_REQUIRED_FOR_ADJUSTMENT` to set this value.
94 ref ac_min_bytes_required_for_adjustment: ByteSize = ByteSize::from("20mb");
95
96 /// The minimum number of completed transmissions that must be observed before we start adjusting the concurrency.
97 /// This ensures we have enough data points to make reliable adjustments.
98 ///
99 /// The default value is 1, meaning we start adjusting the concurrency as soon as we have a completed transmission.
100 ///
101 /// Use the environment variable `HF_XET_CLIENT_AC_NUM_TRANSMISSIONS_REQUIRED_FOR_ADJUSTMENT` to set this value.
102 ref ac_num_transmissions_required_for_adjustment: u64 = 1;
103
104 /// Observations of observed transfer time and deviances are tracked using exponentially
105 /// weighted decay. This is parameterized by the half life in number of samples.
106 /// Thus if this value is 100, it means that observations count for 50% weight after 100 samples, 25% weight
107 /// after 200 samples, etc. This allows us adapt to changing network conditions and give more
108 /// weight to newer observations, but still maintain history.
109 ///
110 /// There are two things being tracked in this model; a prediction of the latency and a record of
111 /// how accurate the model is.
112 ///
113 /// The default value is 64.0.
114 ///
115 /// Use the environment variable `HF_XET_CLIENT_AC_LATENCY_RTT_HALF_LIFE` to set this value.
116 ref ac_latency_rtt_half_life: f64 = 64.0;
117
118 /// Observations of deviance (the ratio of actual vs predicted latency) are tracked using
119 /// exponentially weighted decay. This is parameterized by the half life in number of samples.
120 /// Thus if this value is 8, it means that observations count for 50% weight after 8 samples, 25% weight
121 /// after 16 samples, etc. This allows us adapt to changing network conditions more quickly and give more
122 /// weight to newer observations, but still maintain history.
123 ///
124 /// The default value is 8.0.
125 ///
126 /// Use the environment variable `HF_XET_CLIENT_AC_SUCCESS_TRACKING_HALF_LIFE` to set this value.
127 ref ac_success_tracking_half_life: f64 = 8.0;
128
129 /// The target RTT (in seconds) for increasing concurrency.
130 /// Concurrency is only increased if the predicted RTT is below this target.
131 ///
132 /// The default value is 60 seconds.
133 ///
134 /// Use the environment variable `HF_XET_CLIENT_AC_TARGET_RTT` to set this value.
135 ref ac_target_rtt: Duration = Duration::from_secs(60);
136
137 /// The maximum acceptable RTT (in seconds) for a transfer to be considered successful.
138 /// Transfers taking longer than this are counted as failures.
139 ///
140 /// The default value is 90 seconds.
141 ///
142 /// Use the environment variable `HF_XET_CLIENT_AC_MAX_HEALTHY_RTT` to set this value.
143 ref ac_max_healthy_rtt: Duration = Duration::from_secs(90);
144
145 /// The RTT cutoff quantile used to determine success vs failure.
146 /// A transmission is considered a success if it completes within a healthy time and
147 /// it's within a reasonable margin of error from the predicted rtt for a packet of
148 /// its size. If the rtt actual value is much higher than the predicted rtt, than it can
149 /// indicate unacceptable congestion. Thus in this case, we count values where the actual
150 /// is much higher than the predicted rtt to be a failure, even if they do succeed within a
151 /// healthy total RTT value.
152 ///
153 /// The default value is 0.95.
154 ///
155 /// Use the environment variable `HF_XET_CLIENT_AC_RTT_SUCCESS_MAX_QUANTILE` to set this value.
156 ref ac_rtt_success_max_quantile: f64 = 0.95;
157
158 /// The success ratio threshold above which we increase concurrency.
159 /// When the tracked success ratio exceeds this value, it indicates the connection
160 /// is performing well and can handle more concurrency, provided the RTT is predicted to
161 /// be below the target RTT.
162 ///
163 /// The default value is 0.8.
164 ///
165 /// Use the environment variable `HF_XET_CLIENT_AC_HEALTHY_SUCCESS_RATIO_THRESHOLD` to set this value.
166 ref ac_healthy_success_ratio_threshold: f64 = 0.8;
167
168 /// The success ratio threshold below which we decrease concurrency.
169 /// When the tracked success ratio falls below this value, it indicates the connection
170 /// is struggling and concurrency should be reduced.
171 ///
172 /// The default value is 0.5.
173 ///
174 /// Use the environment variable `HF_XET_CLIENT_AC_UNHEALTHY_SUCCESS_RATIO_THRESHOLD` to set this value.
175 ref ac_unhealthy_success_ratio_threshold: f64 = 0.5;
176
177 /// The maximum reference transmission size used for bandwidth target checks.
178 /// The dynamic reference size (estimated from observed transfer sizes) is capped at this value.
179 ///
180 /// The default value is 64MB.
181 ///
182 /// Use the environment variable `HF_XET_CLIENT_AC_MAX_REFERENCE_TRANSMISSION_SIZE` to set this value.
183 ref ac_max_reference_transmission_size: ByteSize = ByteSize::from("64mb");
184
185 /// The minimum reference transmission size used for bandwidth target checks.
186 /// The dynamic reference size (estimated from observed transfer sizes) is floored at this value
187 /// to prevent excessively aggressive concurrency increases with very small transfers.
188 ///
189 /// The default value is 1MB.
190 ///
191 /// Use the environment variable `HF_XET_CLIENT_AC_MIN_REFERENCE_TRANSMISSION_SIZE` to set this value.
192 ref ac_min_reference_transmission_size: ByteSize = ByteSize::from("1mb");
193
194 /// Log the concurrency on this interval.
195 ///
196 /// The default value is 10 seconds.
197 ///
198 /// Use the environment variable `HF_XET_CLIENT_AC_LOGGING_INTERVAL_MS` to set this value.
199 ref ac_logging_interval_ms: u64 = 10 * 1000;
200
201 /// The maximum number of simultaneous xorb and/or shard upload streams permitted by
202 /// the adaptive concurrency control.
203 ///
204 /// The default value is 64.
205 ///
206 /// Use the environment variable `HF_XET_CLIENT_AC_MAX_UPLOAD_CONCURRENCY` to set this value.
207 ref ac_max_upload_concurrency: usize = 64;
208
209 /// The minimum number of simultaneous xorb and/or shard upload streams that the
210 /// adaptive concurrency control may reduce the concurrency down to on slower connections.
211 ///
212 /// The default value is 2.
213 ///
214 /// Use the environment variable `HF_XET_CLIENT_AC_MIN_UPLOAD_CONCURRENCY` to set this value.
215 ref ac_min_upload_concurrency: usize = 1;
216
217 /// The starting number of concurrent upload streams, which will increase up to max_concurrent_uploads
218 /// on successful completions.
219 ///
220 /// The default value is 2.
221 ///
222 /// Use the environment variable `HF_XET_CLIENT_AC_INITIAL_UPLOAD_CONCURRENCY` to set this value.
223 ref ac_initial_upload_concurrency: usize = 2;
224
225 /// The maximum number of simultaneous download streams permitted by
226 /// the adaptive concurrency control.
227 ///
228 /// The default value is 64.
229 ///
230 /// Use the environment variable `HF_XET_CLIENT_AC_MAX_DOWNLOAD_CONCURRENCY` to set this value.
231 ref ac_max_download_concurrency: usize = 64;
232
233 /// The minimum number of simultaneous download streams that the
234 /// adaptive concurrency control may reduce the concurrency down to on slower connections.
235 ///
236 /// The default value is 1.
237 ///
238 /// Use the environment variable `HF_XET_CLIENT_AC_MIN_DOWNLOAD_CONCURRENCY` to set this value.
239 ref ac_min_download_concurrency: usize = 1;
240
241 /// The starting number of concurrent download streams, which will increase up to max_concurrent_downloads
242 /// on successful completions.
243 ///
244 /// The default value is 4.
245 ///
246 /// Use the environment variable `HF_XET_CLIENT_AC_INITIAL_DOWNLOAD_CONCURRENCY` to set this value.
247 ref ac_initial_download_concurrency: usize = 4;
248
249 /// Path to Unix domain socket for CAS HTTP connections.
250 /// When set, all CAS HTTP traffic uses this socket instead of TCP.
251 /// Only supported on Linux/macOS (not WASM).
252 ///
253 /// The default value is None (use TCP).
254 ///
255 /// Use the environment variable `HF_XET_CLIENT_UNIX_SOCKET_PATH` to set this value.
256 ref unix_socket_path: Option<String> = None;
257
258 /// The reconstruction API version to request from the CAS server.
259 /// When set to 1 or 2, forces that version with no fallback.
260 /// When unset, auto-detects by trying V2 first, falling back to V1 on 404 or 501.
261 ///
262 /// The default value is None (auto-detect).
263 ///
264 /// Use the environment variable `HF_XET_CLIENT_RECONSTRUCTION_API_VERSION` to set this value.
265 ref reconstruction_api_version: Option<u32> = None;
266
267 /// Whether to use multi-range HTTP requests when fetching xorb data.
268 /// When false (default), V2 multi-range fetch entries are split into
269 /// individual single-range requests executed in parallel, which avoids
270 /// slow server-side multirange processing.
271 /// When true, multi-range requests are sent as-is.
272 ///
273 /// The default value is false.
274 ///
275 /// Use the environment variable `HF_XET_CLIENT_ENABLE_MULTIRANGE_FETCHING` to set this value.
276 ref enable_multirange_fetching: bool = false;
277
278});