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