open-net 0.4.0

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
# HTTP client configuration

Required feature: `http-client`. This guide describes the checked-out source. Run the dependency commands from your application crate.

```sh
cargo add open-net --no-default-features --features http-client
cargo add rustls-openssl --no-default-features --features tls12
```

## Application TLS provider

open-net does not choose a cryptographic provider. Each complete program that
creates an HTTP client below initializes the example application's provider in
`main`; copy the program as written. Configuration-only examples need no provider
until a client is built. Client creation requires a provider even for plain HTTP
and otherwise returns `InvalidConfig` for `tls.provider`.

The examples use OpenSSL through `rustls-openssl`, an application dependency.
Another compatible rustls provider can replace it. Install a process provider
once in the host application, or pass an explicit per-client provider. A library
using open-net should accept the host's choice rather than install its own global
provider. See [TLS providers](../tls.md) for build prerequisites, provider
precedence and complete examples of both approaches.

All types below are in `open_net::api::http`; `Duration` is `std::time::Duration`. Configuration builders consume and return ownership of the configuration. Fallible setters consume the original configuration even on `Err(NetError)`; the error does not return it. Clone first if a previous configuration must remain available. `?` returns early on failure. Create a new client to apply changed settings; changing a retained configuration does not reconfigure a running client. `Clone` copies ordinary settings and shares explicitly installed `Arc` providers.

## Construct, validate, and inspect a configuration

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::new(base_url: impl AsRef<str>) -> Result<Self, NetError>
HttpClientConfig::validate(&self) -> Result<(), NetError>
```

### Steps

1. Choose an absolute HTTP or HTTPS base URL.
2. Call `new`, then the relevant `with_*` methods.
3. If you change public fields directly, call `validate` before use. Client construction also validates.
4. Pass the completed value to `HttpClient::new` or the engine's HTTP factory.

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `base_url` | `impl AsRef<str>` | Yes | Absolute `http` or `https` URL with a host; no credentials or fragment. A path and query are allowed. |
| `self` for `validate` | `&HttpClientConfig` | Yes | Configuration to inspect, without mutation. |

Public fields and initial values:

| Field | Type | Default and bounds |
| --- | --- | --- |
| `base_url` | URL value (`reqwest::Url`) | Parsed input; normally construct via `new` without adding reqwest as a dependency. |
| `common_headers` | `HeaderMap` | Empty. SDK-managed transport headers are rejected. |
| `timeout` | `Duration` | 30 seconds per attempt; positive and representable on the monotonic clock. |
| `tcp_keepalive` | `Option<Duration>` | `Some(15 seconds)`; `None` disables it, direct `Some(Duration::ZERO)` is invalid. |
| `max_response_bytes` | `usize` | 1,073,741,824 bytes (1024 MiB); must be positive. Applies to buffered response collection; streaming consumers must enforce their own cumulative byte limit. |
| `request_queue_capacity` | `usize` | 128; `1..=tokio::sync::Semaphore::MAX_PERMITS`. |
| `response_queue_capacity` | `usize` | 128; same range. |
| `callback_queue_capacity` | `usize` | 128; same range. |
| `default_retry_policy` | `HttpRetryPolicy` | `HttpRetryPolicy::no_retry()`. |
| `tls` | `HttpTlsConfig` | Built-in WebPKI roots, no custom roots, client identity or explicit cryptographic provider. |
| `proxy` | `Option<HttpProxyConfig>` | `None`. |
| `environment_proxy` | `bool` | `false`. |

The remaining settings are private. Defaults are: no dedicated connect timeout, inherited phase timeouts, `HttpAdmissionPolicy::Wait`, transport security that prevents HTTPS-to-HTTP redirects, same-origin redirects with at most ten followed hops, no Cookie store, no authentication provider, no middleware, and, with HTTP/2 enabled, `HttpVersionPolicy::Auto` and default `Http2Config`. See [transport security and redirects](redirects.md) for the independent policy setters and migration examples. Optional settings exist only with their respective features.

### Callback parameters

None.

### Return values

`new`: `Ok(HttpClientConfig)` or `Err(NetError)`. `validate`: `Ok(())` or `Err(NetError)`. Neither starts network work. Validation does not test server reachability, proxy credentials, or the remote TLS handshake.

### Errors and behavior

Invalid configuration returns `InvalidConfig`; inspect `error.config_error()` and
its `field()`. A directly mutated public field is checked again at installation.
TLS setters parse bounded PEM material. Client construction resolves the
cryptographic provider and checks the identity's private key and certificate
match; `HttpClientConfig::validate()` does not perform those connector checks.
A missing provider returns `InvalidConfig` for `tls.provider` at client creation.
See [TLS providers](../tls.md) and [TLS identity setup](tls_and_proxy.md).

Relative request paths are resolved using URL joining. For base `https://example.com/api/`, `users` becomes `/api/users`; `/users` becomes `/users`. A base without a trailing slash treats its last component as a file. `..` may traverse the base path while remaining on the same origin. The client trims outer whitespace and rejects empty paths, absolute URLs, `//`, backslashes, fragments, control characters and origin changes. These rules apply to the initial request target. Redirects have their own [policy](redirects.md): they remain on the original origin by default, and cross-origin destinations need an explicit allowlist. The SDK enforces the same rules with or without an [authentication](authentication.md) provider or [Cookie store](cookies.md).

### Example

This is an offline configuration example.

```rust
use open_net::api::http::HttpClientConfig;
use open_net::NetError;

fn main() -> Result<(), NetError> {
    let mut config = HttpClientConfig::new("https://example.com/api/")?;
    config.max_response_bytes = 2 * 1024 * 1024;
    config.validate()?;
    assert_eq!(config.request_queue_capacity, 128);
    Ok(())
}
```

## Headers: `with_common_headers` and `merge_headers`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_common_headers(self, headers: HeaderMap) -> Result<Self, NetError>
HttpClientConfig::merge_headers(&self, request_headers: &HeaderMap) -> Result<HeaderMap, NetError>
```

### Steps

Build a `HeaderMap`, install it as common defaults, and put overrides in each request's header map. `merge_headers` lets you inspect the public merge rule before sending.

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `headers` | `HeaderMap` | Yes | Replaces the entire common map, including when empty. |
| `request_headers` | `&HeaderMap` | Yes | Each present name replaces every common value for that name. Repeated values retain their per-name order. |

### Callback parameters

None.

### Return values

`with_common_headers` returns the updated configuration; `merge_headers` returns a newly owned map. Both return `Err(NetError)` for invalid settings. Neither input to `merge_headers` is modified.

### Errors and behavior

The forbidden names are `connection`, `keep-alive`, `proxy-connection`, `proxy-authenticate`, `proxy-authorization`, `te`, `trailer`, `transfer-encoding`, `upgrade`, `host`, and `content-length`. They produce `InvalidConfig` for `headers`. Typed `HeaderName` and `HeaderValue` construction can separately fail before this API is called. Empty request values still override common values. `merge_headers` first validates the entire configuration.

### Example

```rust
use open_net::api::http::{HeaderMap, HeaderValue, HttpClientConfig};
use open_net::NetError;

fn main() -> Result<(), NetError> {
    let mut common = HeaderMap::new();
    common.insert("accept", HeaderValue::from_static("application/json"));
    common.insert("x-client", HeaderValue::from_static("demo"));
    let config = HttpClientConfig::new("https://example.com/")?
        .with_common_headers(common)?;
    let mut request = HeaderMap::new();
    request.append("accept", HeaderValue::from_static("text/plain"));
    let merged = config.merge_headers(&request)?;
    assert_eq!(merged["accept"], "text/plain");
    assert_eq!(merged["x-client"], "demo");
    Ok(())
}
```

## Time budgets, admission and resource limits

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_timeout(self, timeout: Duration) -> Result<Self, NetError>
HttpClientConfig::with_connect_timeout(self, timeout: Duration) -> Result<Self, NetError>
HttpClientConfig::without_connect_timeout(self) -> Self
HttpClientConfig::connect_timeout(&self) -> Option<Duration>
HttpClientConfig::with_timeouts(self, timeouts: HttpTimeouts) -> Result<Self, NetError>
HttpClientConfig::timeouts(&self) -> &HttpTimeouts
HttpClientConfig::with_admission_policy(self, policy: HttpAdmissionPolicy) -> Self
HttpClientConfig::admission_policy(&self) -> HttpAdmissionPolicy
HttpClientConfig::with_tcp_keepalive(self, keepalive: Duration) -> Self
HttpClientConfig::without_tcp_keepalive(self) -> Self
HttpClientConfig::with_max_response_bytes(self, max_response_bytes: usize) -> Result<Self, NetError>
HttpClientConfig::with_request_queue_capacity(self, request_queue_capacity: usize) -> Result<Self, NetError>
HttpClientConfig::with_response_queue_capacity(self, response_queue_capacity: usize) -> Result<Self, NetError>
HttpClientConfig::with_callback_queue_capacity(self, callback_queue_capacity: usize) -> Result<Self, NetError>
```

### Steps

Set limits before constructing a client. Use request-level timeouts or admission overrides for individual operations. See [timeouts and admission](timeouts_and_admission.md) for phase timing, precedence, and the individual references for `with_connect_timeout`, `without_connect_timeout`, `connect_timeout`, `with_timeouts`, `timeouts`, `with_admission_policy` and `admission_policy`.

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `timeout` | `Duration` | Yes for setters | Positive, monotonic-clock-representable duration; use `from_secs` or `from_millis` for explicit units. |
| `timeouts` | `HttpTimeouts` | Yes | Replaces the complete client override layer; omitted phases inherit fallback values, not the previous layer. |
| `policy` | `HttpAdmissionPolicy` | Yes | `Wait` (default) or `FailFast` for response-returning futures. Does not change `send`/`send_wait`. |
| `keepalive` | `Duration` | Yes | TCP keepalive interval; zero means disable. This is not an HTTP request timeout. |
| `max_response_bytes` | `usize` | Yes | Positive buffered-response body-byte limit. |
| Each queue capacity | `usize` | Yes | Positive number of slots, no greater than `Semaphore::MAX_PERMITS`. |
| Getters and `without_*` methods | None | — | Getters borrow; disabling methods consume and return configuration. |

### Callback parameters

None.

### Return values

Setters return updated configuration, with `Result` where validation can fail. `connect_timeout()` returns `None` when disabled. `timeouts()` returns explicit overrides before inheritance resolution. `admission_policy()` returns the current client default.

### Errors and behavior

Invalid durations, zero body limits, or out-of-range capacities return `InvalidConfig`. The legacy attempt timeout excludes admission, resets on retry, includes preparation and body consumption, and loses precedence to explicit phase settings regardless of setter order. Dedicated connect timeout includes DNS, proxy negotiation and TLS for new connections. Reused connections do not start that budget. TCP keepalive accepts nonzero durations without an additional SDK upper-bound check.

The request quota remains occupied through callback completion or stream completion/drop. Retries retain it while waiting. A buffered response larger than the body limit fails with `ItemTooLarge`; it is not silently truncated. Streaming and SSE consumers must count delivered bytes themselves and drop/cancel the stream when their application limit is reached. Pending callers also retain their own request bodies, so queue capacity alone does not bound all application memory.

### Example

```rust
use open_net::api::http::{HttpAdmissionPolicy, HttpClientConfig, HttpTimeouts};
use open_net::NetError;
use std::time::Duration;

fn main() -> Result<(), NetError> {
    let config = HttpClientConfig::new("https://example.com/")?
        .with_timeout(Duration::from_secs(20))?
        .with_connect_timeout(Duration::from_secs(3))?
        .without_connect_timeout()
        .with_timeouts(HttpTimeouts::new().with_total_timeout(Duration::from_secs(30)))?
        .with_admission_policy(HttpAdmissionPolicy::FailFast)
        .with_tcp_keepalive(Duration::from_secs(15))
        .without_tcp_keepalive()
        .with_max_response_bytes(1024 * 1024)?
        .with_request_queue_capacity(16)?
        .with_response_queue_capacity(16)?
        .with_callback_queue_capacity(16)?;
    assert_eq!(config.connect_timeout(), None);
    assert_eq!(config.admission_policy(), HttpAdmissionPolicy::FailFast);
    let _overrides = config.timeouts();
    config.validate()
}
```

## Extension configuration map

Every method below consumes `self` and returns an updated configuration; later installation replaces the previous value except middleware, which appends. The complete signatures, inputs, return values, callbacks, errors and examples are in the linked guide.

| Methods | Required feature | Guide |
| --- | --- | --- |
| `with_default_retry_policy(policy: HttpRetryPolicy) -> Self` | `http-client` | [Retry](retry.md) |
| `with_tls(tls: HttpTlsConfig) -> Self`, `with_proxy(proxy: HttpProxyConfig) -> Self`, `with_environment_proxy(enabled: bool) -> Self` | `http-client` | [TLS and proxies](tls_and_proxy.md) |
| `with_cookie_store<S: CookieStore + 'static>(store: S) -> Self`, `with_cookie_store_arc(store: Arc<dyn CookieStore>) -> Self`, `with_cookie_limits(limits: CookieLimits) -> Result<Self, NetError>` | `http-client-cookies` | [Cookies](cookies.md) |
| `with_auth<A: HttpAuth + 'static>(auth: A) -> Self`, `with_auth_arc(auth: Arc<dyn HttpAuth>) -> Self` | `http-client-auth` | [Authentication](authentication.md) |
| `with_middleware<M: HttpMiddleware + 'static>(middleware: M) -> Self`, `with_middleware_arc(middleware: Arc<dyn HttpMiddleware>) -> Self` | `http-client-middleware` | [Middleware](middleware.md) |
| `with_http_version_policy(policy: HttpVersionPolicy) -> Self`, `with_http2(http2: Http2Config) -> Result<Self, NetError>` | `http-client-http2` | [HTTP/2](http2.md) |

## Individual function reference

The examples linked below are complete programs using the dependencies listed at the top of this page. Each reference identifies the call that demonstrates the function.

## `HttpClientConfig::new()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::new(base_url: impl AsRef<str>) -> Result<Self, NetError>
```

### Steps

Pass an absolute base URL, apply setters, then create the client with the returned configuration.

### Parameters

`base_url` is required and borrowed for parsing. It must be an absolute `http` or `https` URL with a host, without credentials or a fragment. Path and query are allowed.

### Callback parameters

None.

### Return values

`Ok(HttpClientConfig)` with the defaults listed above; `Err(NetError)` for invalid input.

### Errors and behavior

Returns `InvalidConfig` for `base_url` on invalid syntax or unsupported URL components. Parsing and construction perform no network I/O; later `validate` checks changes to public fields.

### Example

See the [complete construction program](#construct-validate-and-inspect-a-configuration), which calls `HttpClientConfig::new` and `config.validate()` after changing a public field.

## `HttpClientConfig::with_standalone_quality_doctor()`

### Required features

`http-client` and `quality-doctor`.

### Function signature

```text
pub fn with_standalone_quality_doctor(self, config: QualityDoctorConfig) -> Self
```

### Steps

Set the policy before calling `HttpClient::new` or `new_with_network_status`.
Call `client.quality_doctor()` to activate collection before submitting work.

### Parameters

`config` selects the mode, protocols, storage limits and sampling policy.
Include HTTP in the protocol selection to observe HTTP requests.

### Callback parameters

None.

### Return values

The updated `HttpClientConfig`. Standalone diagnostics default to Off.

### Errors and behavior

The setter stores the policy. Config validation and client construction check
it and return `InvalidConfig` for `http.quality_doctor` on failure. Engine-managed
clients inherit their engine's policy and reject an explicit standalone policy,
including Off.

### Example

[Configure a standalone HTTP client for detailed collection](../quality_doctor.md#standalone-http-example).

## `HttpClientConfig::validate()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::validate(&self) -> Result<(), NetError>
```

### Steps

Call after mutating public fields, or before handing a completed configuration to client construction.

### Parameters

Only the borrowed configuration receiver; it is not modified.

### Callback parameters

None.

### Return values

`Ok(())` when local invariants pass, otherwise `Err(NetError)`.

### Errors and behavior

Checks URL, headers, durations, queue capacities, response limit and enabled extension bounds. Errors are `InvalidConfig`; inspect the structured field. This does not prove reachability, proxy credentials or successful TLS negotiation. Client construction also validates.

### Example

See the [complete construction program](#construct-validate-and-inspect-a-configuration), which calls `HttpClientConfig::new` and `config.validate()` after changing a public field.

## `HttpClientConfig::with_common_headers()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_common_headers(self, headers: HeaderMap) -> Result<Self, NetError>
```

### Steps

Build a typed map, pass it to this setter, and retain the returned configuration.

### Parameters

`headers` is a required owned map. Empty clears all common headers. Per-request values later replace common values by name.

### Callback parameters

None.

### Return values

`Ok(Self)` with the complete replacement map, or `Err(NetError)`.

### Errors and behavior

Rejects the SDK-managed transport names listed in the headers overview with `InvalidConfig` for `headers`. The consumed input configuration is not returned on failure. This replaces the map rather than merging it.

### Example

See the [complete headers program](#headers-with_common_headers-and-merge_headers), which installs `common` with `with_common_headers(common)` and calls `config.merge_headers(&request)`.

## `HttpClientConfig::merge_headers()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::merge_headers(&self, request_headers: &HeaderMap) -> Result<HeaderMap, NetError>
```

### Steps

Prepare request headers and call this accessor to inspect the same name-based merge used by submission.

### Parameters

`request_headers` is required and borrowed; both it and the configuration remain unchanged.

### Callback parameters

None.

### Return values

`Ok(HeaderMap)` containing an owned merged map, or `Err(NetError)`.

### Errors and behavior

Validates the entire configuration first, then the request map. Invalid configuration or managed transport headers return `InvalidConfig`. A present request name replaces all common values of that name, preserving repeated request values and their order, including empty values.

### Example

See the [complete headers program](#headers-with_common_headers-and-merge_headers), which installs `common` with `with_common_headers(common)` and calls `config.merge_headers(&request)`.

## `HttpClientConfig::with_timeout()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_timeout(self, timeout: Duration) -> Result<Self, NetError>
```

### Steps

Choose the legacy per-attempt duration, call the setter, and install the returned configuration.

### Parameters

`timeout` is required, positive and representable on the monotonic clock. Use explicit seconds or milliseconds.

### Callback parameters

None.

### Return values

`Ok(Self)` with the replacement legacy timeout, or `Err(NetError)`.

### Errors and behavior

Invalid values return `InvalidConfig` for `http.timeout`. The timeout excludes admission and resets per retry; preparation and body consumption use it. Explicit `HttpTimeouts` attempt settings take precedence regardless of setter order. See [phase timeouts](timeouts_and_admission.md).

### Example

See the [complete limits program](#time-budgets-admission-and-resource-limits), which calls `with_timeout(Duration::from_secs(20))`.

## `HttpClientConfig::with_tcp_keepalive()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_tcp_keepalive(self, keepalive: Duration) -> Self
```

### Steps

Choose a TCP keepalive interval before client construction and retain the returned configuration.

### Parameters

`keepalive` is required. Zero disables TCP keepalive; any nonzero duration is retained as the interval.

### Callback parameters

None.

### Return values

The updated owned configuration.

### Errors and behavior

Infallible; no additional SDK upper-bound check is applied. This controls pooled TCP connections, independently of request deadlines and HTTP/2 PINGs. It does not send an application HTTP health check.

### Example

See the [complete limits program](#time-budgets-admission-and-resource-limits), which calls `with_tcp_keepalive(Duration::from_secs(15))` before disabling it.

## `HttpClientConfig::without_tcp_keepalive()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::without_tcp_keepalive(self) -> Self
```

### Steps

Call before client construction to remove the configured TCP keepalive interval.

### Parameters

Only the consumed configuration receiver.

### Callback parameters

None.

### Return values

The updated configuration with `tcp_keepalive = None`.

### Errors and behavior

Infallible and idempotent. It does not change HTTP phase timeouts or HTTP/2 PING settings.

### Example

See the [complete limits program](#time-budgets-admission-and-resource-limits), which calls `without_tcp_keepalive()` after setting an interval.

## `HttpClientConfig::with_max_response_bytes()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_max_response_bytes(self, max_response_bytes: usize) -> Result<Self, NetError>
```

### Steps

Choose a maximum buffered response-body size and pass it in bytes before client creation.

### Parameters

`max_response_bytes` is required and must be greater than zero; the default is 1,073,741,824 bytes.

### Callback parameters

None.

### Return values

`Ok(Self)` with the new byte limit, or `Err(NetError)`.

### Errors and behavior

Zero returns `InvalidConfig` for `max_response_bytes`. A buffered response that exceeds this limit returns `ItemTooLarge`; it is not truncated. Streaming and SSE consumers must enforce their own cumulative limit.

### Example

See the [complete limits program](#time-budgets-admission-and-resource-limits), which calls `with_max_response_bytes(1024 * 1024)`.

## `HttpClientConfig::with_request_queue_capacity()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_request_queue_capacity(self, request_queue_capacity: usize) -> Result<Self, NetError>
```

### Steps

Choose the request queue slot count before constructing the client and retain the returned configuration.

### Parameters

`request_queue_capacity` is required, measured in slots, and must be in `1..=tokio::sync::Semaphore::MAX_PERMITS`. The default is 128.

### Callback parameters

None.

### Return values

`Ok(Self)` with the replacement capacity, or `Err(NetError)`.

### Errors and behavior

Zero or an out-of-range value returns `InvalidConfig` for `request_queue_capacity`. Request quota remains occupied through callback completion or stream completion/drop, including retry waits. Caller-owned pending bodies are not bounded by this value.

### Example

See the [complete limits program](#time-budgets-admission-and-resource-limits), which calls `with_request_queue_capacity(16)`.

## `HttpClientConfig::with_response_queue_capacity()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_response_queue_capacity(self, response_queue_capacity: usize) -> Result<Self, NetError>
```

### Steps

Choose the response queue slot count before constructing the client and retain the returned configuration.

### Parameters

`response_queue_capacity` is required, measured in slots, and must be in `1..=tokio::sync::Semaphore::MAX_PERMITS`. The default is 128.

### Callback parameters

None.

### Return values

`Ok(Self)` with the replacement capacity, or `Err(NetError)`.

### Errors and behavior

Zero or an out-of-range value returns `InvalidConfig` for `response_queue_capacity`. Bounds queued buffered response work. It is independent of the request and callback queue settings.

### Example

See the [complete limits program](#time-budgets-admission-and-resource-limits), which calls `with_response_queue_capacity(16)`.

## `HttpClientConfig::with_callback_queue_capacity()`

### Required features

`http-client`.

### Function signature

```text
HttpClientConfig::with_callback_queue_capacity(self, callback_queue_capacity: usize) -> Result<Self, NetError>
```

### Steps

Choose the callback queue slot count before constructing the client and retain the returned configuration.

### Parameters

`callback_queue_capacity` is required, measured in slots, and must be in `1..=tokio::sync::Semaphore::MAX_PERMITS`. The default is 128.

### Callback parameters

None.

### Return values

`Ok(Self)` with the replacement capacity, or `Err(NetError)`.

### Errors and behavior

Zero or an out-of-range value returns `InvalidConfig` for `callback_queue_capacity`. Bounds callback queue slots. Slow callbacks still delay completion; this value does not bound application work detached by a callback.

### Example

See the [complete limits program](#time-budgets-admission-and-resource-limits), which calls `with_callback_queue_capacity(16)`.

[HTTP guide index](README.md)