Expand description
Runtime-independent HTTP, DNS and TCP/TLS for Rust applications.
The crate implements NBReq’s backend-independent ownership and lifecycle kernel. Compiled HTTP
implementations can be selected explicitly with EngineBuilder::http_backend. The default
build and ordinary Engine::new constructor use NBReq’s native HTTP implementation.
Engine::tcp_connector issues a cloneable capability ticket for plain TCP, verified direct
TLS and consuming TLS upgrades within the same Engine lifecycle.
The default-on resolver feature additionally exposes public hostname resolution through
Engine::resolver. Both capabilities use the Engine-owned native DNS and reactor owners.
§Using NBReq
For complete programs in learning order, see the HTTP, DNS and TCP/TLS examples.
NBReq is built around one explicit owner. An Engine owns network state, pools, DNS work, callback
workers, limits, and shutdown. It issues cheap cloneable Client command handles, but a Client
neither owns nor extends the Engine’s lifetime. Keep the Engine in the service or module that is
responsible for stopping HTTP.
The default Cargo features are native and resolver. They provide NBReq’s Rust-native HTTP/1.1,
DNS, TCP, public Resolver, and rustls implementation without Tokio or another async runtime.
This guide targets NBReq 0.3.1. Add the dependency below to use the default native backend:
[dependencies]
nbreq = "0.3.1"An HTTP-only consumer can omit the public Resolver API and its Windows search-suffix registry
reader while retaining native HTTP and exact-name DNS for HTTP and hostname TcpConnector:
[dependencies]
nbreq = { version = "0.3.1", default-features = false, features = ["native"] }The resolver feature implies native. Turning it off does not use a blocking OS resolver and does
not create a different DNS owner; it only removes the public Resolver surface and search expansion.
§Basic buffered requests
Spawned mode owns its reactor thread and supports simple Engine-bound blocking GET and POST calls. The convenience builder delegates to the ordinary Request and Client path, so it uses the same backend, pool, limits, timeouts, redirects, TLS policy, errors, and shutdown owner:
use std::time::Duration;
use nbreq::{Engine, EngineConfig};
let engine = Engine::new(EngineConfig::spawned())?;
let response = engine
.get("https://example.com/")
.header("Accept", "text/plain")
.total_timeout(Duration::from_secs(30))
.call()?;
let created = engine
.post("https://httpbin.org/post")
.header("Content-Type", "application/json")
.total_timeout(Duration::from_secs(30))
.send(br#"{"name":"thing"}"#)?;
println!("GET {}, POST {}", response.status(), created.status());
engine.shutdown()?;call() sends the body already configured on the builder and is valid for an empty POST.
send(body) replaces that buffered body; send_empty() explicitly replaces it with an empty body.
HTTP 4xx and 5xx statuses remain ordinary Response values. These blocking terminals reject a
manually driven Engine with WrongMode rather than driving it implicitly.
§Buffered response ownership
response.body() still borrows a byte slice, and response.body().to_vec() explicitly copies it
into independent application storage. Cloning a Response now shares its immutable body bytes;
headers are still cloned. Completion delivery moves the response to its waiter or callback.
Use consuming access to take the original buffer when it has no other owners:
use nbreq::Response;
let response = Response::new(200, Vec::new(), b"hello".to_vec());
let body = response.into_body();
let bytes = match body.try_into_vec() {
Ok(bytes) => bytes, // Original allocation, including spare capacity; no byte copy.
Err(shared) => shared.as_bytes().to_vec(), // An explicit application choice to copy.
};
let text = String::from_utf8(bytes)?; // Reuses the Vec allocation for valid UTF-8.
assert_eq!(text, "hello");ResponseBody is cloneable, immutable and shareable between threads. Its as_bytes() and
AsRef<[u8]> accessors borrow bytes. try_into_vec() returns the original body owner in Err
while any other response/body shares that allocation; it never silently copies. Instead of
copying, callers can drop their other owners and retry. Taking a Vec transfers responsibility
for its memory to the application. It does not free RAM. A retained body can outlive Engine
shutdown without keeping sockets or workers alive.
These APIs also define how the optional aggregate buffered-body budget retains and releases charges. See the memory controls below. The API does not promise zero-copy network or TLS I/O.
§Spawned mode and explicit blocking requests
Issue a cheap cloneable Client when code needs the explicit Request surface or will later use callbacks, direct waiters, cancellation handles, or streaming. The Client does not own or extend the Engine lifetime:
use std::time::Duration;
use nbreq::{Engine, EngineConfig, Request};
let engine = Engine::new(EngineConfig::spawned())?;
let client = engine.client();
let request = Request::get("https://example.com/")
.connect_timeout(Duration::from_secs(5))
.inactivity_timeout(Duration::from_secs(10))
.total_timeout(Duration::from_secs(30))
.build()?;
let response = client.execute(request)?;
println!("HTTP {}", response.status());
engine.shutdown()?;execute returns a Response only for completed HTTP exchanges. A 404 or 500 remains a Response;
transport, timeout, policy, and cancellation outcomes are errors. Total timeout begins when NBReq
accepts the request, so queue time is included. TLS certificate and hostname verification is on by
default. Keep verification enabled when choosing a trust policy.
§Certificate trust and private authorities
Add DER-encoded root certificates to an Engine when an application uses a private CA. The roots supplement platform trust, without modifying the operating-system trust store. Hostname, validity and signature verification stay enabled:
use nbreq::{Engine, EngineConfig};
let root_der = std::fs::read("company-root.der")?;
let config = EngineConfig::spawned().with_additional_tls_root_certificate(root_der);
let engine = Engine::new(config)?; // Rejects malformed certificates during construction.
let response = engine.get("https://internal.example/").call()?;
engine.shutdown()?;Call the configuration method once per root. An Engine’s trust policy is fixed at construction and applies to HTTPS requests and redirects, direct TLS and STARTTLS; use separate Engines for separate trust domains. Additional roots are parsed as WebPKI trust anchors before entering the selected verifier, including platform mode. A certificate accepted or ignored differently by the OS in 0.2.0 can therefore fail construction in 0.2.1. Windows, Linux and macOS use the existing platform verifier with extra roots. The current platform verifier dependency does not support this option on Android in platform mode and rejects a nonempty extra-root configuration explicitly.
To trust only your supplied DER roots, select TlsTrust::SuppliedRootsOnly before constructing
the Engine:
use nbreq::{Engine, EngineConfig, TlsTrust};
let config = EngineConfig::spawned()
.with_tls_trust(TlsTrust::SuppliedRootsOnly)
.with_additional_tls_root_certificate(std::fs::read("company-root.der")?);
let engine = Engine::new(config)?;
engine.shutdown()?;For bundled Mozilla roots, enable the feature and explicitly select the policy:
[dependencies]
nbreq = { version = "0.3.1", features = ["bundled-roots"] }use nbreq::{Engine, EngineConfig, TlsTrust};
let engine = Engine::new(
EngineConfig::spawned().with_tls_trust(TlsTrust::BundledMozilla),
)?;
engine.shutdown()?;Platform trust remains the default even with bundled-roots enabled. Both portable policies
retain certificate signatures, validity and DNS/IP identity checks, but do not import OS
enterprise roots, distrust rules or revocation retrieval, and do not add online revocation
checking. No automatic fallback or verification bypass is part of trust selection.
Malformed roots, empty supplied-only trust and unsupported policies fail Engine construction;
configurations a backend cannot apply return Unsupported, including public test-support
held/HTTP-only constructors. Use an HTTPS fixture or omit unused trust settings in those tests.
The Mozilla roots are compiled into the application. Update the application’s dependency lockfile, rebuild and redeploy to refresh them; running processes do not fetch new roots. See trust selection and bundle updates.
§Callbacks and direct waiters
Client::start queues one FnOnce callback after the canonical terminal result is committed. User
code never runs on the network reactor or while the request registry is locked. In spawned mode the
callback runs on the Engine-owned callback pool:
use nbreq::{Completion, Engine, EngineConfig, Request};
let engine = Engine::new(EngineConfig::spawned())?;
let client = engine.client();
let handle = client.start(Request::get("https://example.com/").build()?, |result| {
match result {
Completion::Completed(response) => println!("HTTP {}", response.status()),
Completion::Failed(error) => eprintln!("request failed: {error}"),
Completion::Cancelled => eprintln!("request cancelled"),
_ => {}
}
})?;
// Idempotent if completion has already won.
handle.cancel()?;
engine.shutdown()?;Use Client::submit when the calling code wants a unique direct waiter instead. PendingRequest
can be polled, waited with a caller-local timeout, or given to a manual Engine’s drive_until.
A waiter timeout does not cancel its request.
§Cancellation
Each accepted request has a cloneable cancellation-only RequestHandle. cancel is idempotent
after a terminal result and never recalls bytes already accepted by the operating system or acted
on by a remote server. CancelOnDrop is useful when cancellation should follow a local scope.
Engine::cancel_all cancels the entire Engine domain. It is appropriate during service shutdown;
independent cancellation domains should use independent Engines.
§Streaming responses and uploads
Every StreamRequest has a streaming response and returns one unique ResponseReader. A buffered
body remains replayable; body_stream consumes one unique UploadBody and redirects are returned
unfollowed once a live upload is involved.
use nbreq::{Engine, EngineConfig, StreamRequest, UploadBody};
let engine = Engine::new(EngineConfig::spawned())?;
let client = engine.client();
let (body, mut sender) = UploadBody::chunked(256 * 1024)?;
let request = StreamRequest::post("https://httpbin.org/post")
.header("Content-Type", "application/octet-stream")
.body_stream(body)
.build()?;
let reader = client.submit_stream(request)?;
sender.push(vec![0_u8; 64 * 1024])?;
sender.finish()?;
let response = reader.collect()?;
println!("HTTP {}", response.status());
engine.shutdown()?;UploadBody::fixed generates Content-Length and requires exactly the declared byte count before
finish. UploadBody::chunked generates HTTP/1.1 chunk framing and permits an unknown total.
try_push never blocks and returns ownership of a refused chunk. Spawned-mode push admits large
chunks progressively and wakes on capacity, early response, cancellation, failure, or Engine stop.
ResponseReader::wait_head, read, and collect block only in spawned mode. Their try_*
counterparts are passive and are suitable for manual driving. collect is valid only before any
body byte has been consumed. Dropping a reader before known EOF requests cancellation; dropping it
after final EOF or a no-body response is harmless.
§Errors and TLS diagnosis
Use the structured fields on Error for decisions and treat message() as a payload-free human
diagnostic. In particular, transport_stage() identifies DNS, connect, TLS, send, receive, or HTTP
framing, while tls_failure() can distinguish safe categories such as hostname mismatch, unknown
issuer, expiry, peer alert, protocol failure, and local TLS I/O. Both enums are non-exhaustive, so
portable callers must retain a fallback arm:
use nbreq::{Error, TlsFailure};
fn tls_hint(error: &Error) -> &'static str {
match error.tls_failure() {
Some(TlsFailure::CertificateHostnameMismatch) => "check the requested hostname",
Some(TlsFailure::CertificateUnknownIssuer) => "check the installed trust roots",
Some(TlsFailure::CertificateExpired) => "renew the server certificate",
Some(_) => "inspect the TLS category and deployment",
None => "this was not a classified TLS failure",
}
}NBReq deliberately provides no raw-TLS-diagnostic switch: backend-native certificate errors can contain requested or presented names. The structured category preserves operational usefulness without making ordinary logging a data-disclosure path.
§Ambiguous HTTP response framing
The native HTTP/1.1 backend rejects a response containing both Transfer-Encoding and
Content-Length, even when a legacy server intended a valid chunked body. The result is a
transport error at the HTTP stage. This avoids accepting ambiguous framing that can cause
response splitting or disagreement between intermediaries; no permissive compatibility switch
is provided. See RFC 9112 section 6.3.
§Manual driving and GUI loops
Manual mode creates no reactor thread and dispatches callbacks inline only from explicit drive
calls. The unique Engine owner must call drive; Client methods and readers never drive it
implicitly:
use nbreq::{Completion, EngineBuilder, Request};
let mut engine = EngineBuilder::manual().build()?;
let client = engine.client();
let pending = client.submit(Request::get("https://example.com/").build()?)?;
match engine.drive_until(pending)? {
Completion::Completed(response) => println!("HTTP {}", response.status()),
Completion::Failed(error) => eprintln!("request failed: {error}"),
Completion::Cancelled => eprintln!("request cancelled"),
_ => {}
}
engine.shutdown()?;For a GUI with spawned networking, keep the Engine in an application service and have callbacks
send owned results through the GUI framework’s own message/channel mechanism. Do not perform long
GUI work on NBReq’s callback worker. Manual mode is useful only when the host can integrate regular
drive calls and accepts that delaying them delays all network progress.
Native TLS handshake processing uses an Engine-owned service, started lazily, with at most two
workers and four queued steps. These workers process supplied TLS bytes; sockets and application
callbacks stay with their existing owners. Established TLS traffic does not use the worker queue.
In manual mode, worker completion becomes network progress only on a subsequent drive call.
Saturated workers delay new handshakes within the existing connection limits and request deadlines.
§Shutdown, DLLs, and FFI ownership
Engine::shutdown consumes the unique owner, rejects new work, cancels accepted requests, stops and
joins network/resolver/TLS-worker work, seals callback admission, and waits for callbacks. A
callback that is itself currently running can therefore delay ordinary shutdown.
Cancellation and request deadlines close the request’s NBReq socket without waiting for an executing platform certificate check. That check may not be interruptible: its worker and TLS state remain owned and bounded until it returns. Shutdown discards queued handshake work and closes sockets before joining executing checks, so a slow platform check can delay shutdown.
shutdown_for can detach only the already-network-free callback domain and return
ShutdownOutcome::CallbacksRemaining. Keep the resulting DetachedCallbacks handle and wait for
it before unloading a module containing callback code. The handle owns no Engine, socket, resolver,
TLS, or backend state.
The shutdown_for duration bounds callback draining after network shutdown; it does not set a
deadline for joining executing platform certificate checks.
An FFI layer should expose opaque ownership handles: one unique Engine/service handle and separate
cloneable Client/request-control handles. Destroy consumer objects, stop the Engine, resolve any
detached callback handle, and only then permit library unload. Never initialize networking from a
Windows DllMain loader callback.
§Limits, pools, and metrics
Engine construction owns all resource ceilings: inflight requests, command and callback queues, request/response bodies and headers, stream windows and aggregate queued bytes, active connections, idle connections, and idle lifetime. Tighten them for the application; do not create an unbounded Client-specific escape hatch.
Engine::metrics is a nonblocking, approximate, payload-free snapshot. Request and bounded-queue
metrics are portable. Check connection_metrics_available before interpreting physical
connection/pool counters; the native owner supplies them, while internal non-networking test
backends report honest unavailable zeroes.
§Timeout and queue defaults
NBReq 0.3.1 bounds ordinary network operations by default. Quiet established TCP/TLS connections stay open: connected read inactivity has no default deadline, and write inactivity runs only while accepted output awaits progress. The deadlines below do not bound connection lifetime.
| Setting | Default | Override |
|---|---|---|
| Buffered HTTP connect, inactivity and total timeouts | 10, 30 and 120 seconds | Request/builder connect_timeout, inactivity_timeout, total_timeout, or RequestOptions |
| Fresh streaming HTTP builders | 10-second connect, 30-second inactivity; no total cap | The same three setters on StreamRequestBuilder |
| Public DNS total timeout | 30 seconds; internal per-server retries are separate | ResolveRequestBuilder::total_timeout |
| Plain TCP connect | 10 seconds from admission, including DNS | TcpConnectRequestBuilder::connect_timeout |
| Connected TCP/TLS read inactivity | None; idle connections are valid | TcpConnectRequestBuilder::read_inactivity_timeout |
| Connected TCP/TLS write inactivity | 30 seconds while accepted output awaits progress | TcpConnectRequestBuilder::write_inactivity_timeout |
| TLS establishment | 10 seconds from admission, including immediate-TLS DNS/TCP and certificate verification | TlsOptions::handshake_timeout; an earlier configured connect deadline also applies to direct TLS |
| TCP/TLS send and receive queue windows | Each inherits the Engine’s 256 KiB per-connection queue ceiling | TcpConnectRequestBuilder::send_queue_bytes and receive_queue_bytes |
HTTP/DNS/TCP timeout setters accept Duration, Some(Duration) or None. Omission chooses
the default; explicit None disables that timer. Zero is not a disabling sentinel. For example:
use std::time::Duration;
use nbreq::Request;
let request = Request::get("https://example.com/")
.connect_timeout(Some(Duration::from_secs(20)))
.inactivity_timeout(None)
.total_timeout(None)
.build()?;RequestOptions::default() contains the buffered defaults. StreamRequest::from(request)
preserves the source request’s complete options, including any total cap. Supplying .options(...)
also replaces the complete options object. For streaming, inactivity_timeout(None) permits long
quiet periods or a slow upload producer; no total cap alone does not disable inactivity.
The total clock begins at admission and includes queueing and HTTP redirects. Redirects renew the existing per-hop connect/inactivity clocks but never the total budget. Useful progress resets inactivity, and response-consumer backpressure pauses it. Waiting for an empty streaming upload producer does not pause HTTP inactivity. Public DNS’s total default is independent of internal HTTP/TCP DNS, which uses the enclosing operation’s budgets.
Direct TLS takes the earlier TCP connect and TLS establishment deadline. To extend establishment
beyond ten seconds, also raise the TCP connect timeout or pass connect_timeout(None); the
existing finite TlsOptions::handshake_timeout(Duration) still applies. A STARTTLS upgrade starts
a fresh TLS deadline. Local wait_for expiry leaves the operation alive, and a manual Engine
still needs explicit driving to process deadlines. See the
0.3 migration guide.
Set EngineBuilder::max_tcp_queue_bytes_per_connection or
EngineConfig::with_max_tcp_queue_bytes_per_connection to change the queue ceiling; requested
windows must fit it. The shared max_queued_bytes budget defaults to 16 MiB and governs admission
across reserved TCP/TLS windows, TLS staging and HTTP streaming windows. Override it with
EngineBuilder::max_queued_bytes or EngineConfig::with_max_queued_bytes. Queue reservations
are not all eagerly allocated, and these limits are not a cap on total process memory.
Choose connected read/write timeouts for the application protocol even when using the default TLS handshake deadline. The cleartext TCP example below shows explicit overrides; C04/C05 show commented timeout defaults and explicit queue sizes. The TLS guide uses the default establishment deadline and queue windows.
§DNS resolution
With the default-on resolver feature, Engine::resolver() issues a cheap cloneable ticket
into the Engine’s existing DNS service. Use execute in spawned mode, submit for a direct
waiter, or start for a callback. A valid negative DNS answer is a ResolveResponse, not a
transport error:
use std::time::Duration;
use nbreq::{Engine, ResolveRequest, ResolveStatus};
let engine = Engine::builder().build()?;
let answer = engine.resolver().execute(
ResolveRequest::hostname("example.com")
.total_timeout(Duration::from_secs(10))
.build()?,
)?;
match answer.status() {
ResolveStatus::Answer => {
for address in answer.addresses() {
println!("{}", address.address());
}
}
ResolveStatus::NameNotFound => println!("name does not exist"),
ResolveStatus::NoData => println!("no addresses in the requested families"),
_ => {}
}
engine.shutdown()?;Names must be ASCII or already punycode-encoded. Lookups are exact by default; search-suffix
expansion is explicit through use_search_suffixes(true), and a trailing dot keeps the lookup
absolute. This is a DNS API, not a replacement for every OS name service such as mDNS or hosts-file
lookup. AddressFamily::Both collects A and AAAA; failure of either required family fails the
operation instead of presenting a partial answer. It does not promise Happy Eyeballs.
CacheMode::Use reads/populates the shared Engine cache; Refresh skips the read and replaces
the network result, and Bypass neither reads nor populates it. Public refreshes can affect later
HTTP lookups. HTTP and hostname TCP remain exact-name even when public search expansion is enabled.
In manual mode, pass a submitted PendingResolve to engine.drive_until(pending) or drive and
poll it explicitly. Blocking execute rejects manual mode. Direct waiters never drive the
Engine: use wait_for(Duration::ZERO) to poll and recover a pending waiter from TimedOut;
calling wait() on its undriven owner thread cannot make network progress.
§Cleartext TCP connections
Engine::tcp_connector() provides literal-address and exact-hostname connects on the same
reactor. It is available with native, even when the public Resolver feature is disabled.
The ordinary execute call returns a cleartext byte stream with no message framing:
use std::time::Duration;
use nbreq::{Engine, TcpConnectRequest};
let engine = Engine::builder().build()?;
let request = TcpConnectRequest::literal("127.0.0.1:9000".parse()?)
.connect_timeout(Duration::from_secs(5))
.read_inactivity_timeout(Duration::from_secs(10))
.write_inactivity_timeout(Duration::from_secs(10))
.send_queue_bytes(16 * 1024)
.receive_queue_bytes(16 * 1024)
.build()?;
let mut connection = engine.tcp_connector().execute(request)?;
connection.send(b"hello\n".to_vec())?;
connection.finish()?; // Drain output and half-close; keep reading the reply.
let mut buffer = [0_u8; 1024];
while let Some(count) = connection.read(&mut buffer)? {
println!("received {count} bytes");
}
drop(connection);
engine.shutdown()?;This example expects a local server that replies and closes after client EOF. For a hostname,
use TcpConnectRequest::hostname("server.example", port); address attempts are serial, not
parallel Happy Eyeballs. Connect timeout includes queueing and DNS. Read/write inactivity timers
apply after connection; consumer backpressure pauses read inactivity, and write inactivity runs
only while accepted output waits for socket progress.
try_send returns refused input unchanged; blocking send can accept a prefix before failing,
so TcpSendError::into_remaining() returns only the unaccepted suffix. Retrying the original whole
message can duplicate its accepted prefix. A successful send means bytes were queued, not that
the peer processed them. Bound each chunk to the configured send window for passive try_send.
Accepted plain TCP buffers shed excess Vec capacity, which may allocate or copy; refused buffers
retain their allocation. Receive storage uses bounded windows. Peer FIN remains EOF, and later
queue-pressure changes do not restart the read inactivity timer after it.
For manual driving use submit/drive_until to connect and passive try_read, try_send and
try_finish between drive calls. Blocking connected methods reject manual mode. split moves
one connection into unique reader/writer halves; each is Send but not Sync. Dropping a reader
before EOF or a writer before requesting finish aborts the connection. A successful try_finish
or finish_with requests drain-then-half-close; the split writer may then be dropped, but the
reader still needs to drain to EOF. Dropping an unsplit connection before EOF also aborts it.
Use a cloned connection handle to cancel from another thread.
§Verified TCP TLS and upgrades
Use TcpConnector::execute_tls(request, options) for immediate TLS, or negotiate the application’s
upgrade protocol over an unsplit TcpConnection and consume it with into_tls(options).
TlsOptions names the DNS name or IP identity the certificate must authenticate; it can differ
from the address used to reach the peer. Both paths verify TLS before returning a TlsConnection.
submit_tls and start_tls provide waiter and callback forms, and a manual Engine can drive a
PendingTlsConnect with drive_until. Engine::run_mode() reports who owns progress.
Drain the complete positive plaintext upgrade response and leave no unread or queued plaintext
at the boundary. Every consuming-upgrade failure closes the original connection. Standalone TLS
has no automatic plaintext fallback or verification-disable option. On an established TLS
connection, a raw transport EOF without the TLS close alert is TlsFailure::Truncated;
TLS 1.2 and 1.3 differ in half-close behavior.
See the TCP TLS guide and
local direct-TLS and upgrade examples
for complete programs, closure rules and additional memory reservations.
§Backend and feature selection
| Cargo selection | Available behavior |
|---|---|
| Default | Native HTTP/1.1, TLS, internal DNS, standalone TCP and public Resolver |
default-features = false, features = ["native"] | Native HTTP/TLS/TCP and internal exact-name DNS; no public Resolver or Windows search-suffix registry reader |
bundled-roots | Enables native and optional Mozilla roots; explicitly select TlsTrust::BundledMozilla to use them; default trust remains platform |
| No features | Portable configuration/HTTP/TCP types compile; public Resolver is absent and Engine construction returns Unsupported |
test-support | Additional deterministic test controls; does not select a network backend or add production capabilities |
The historical curl Multi pilot is not part of the public crate feature matrix. It required a locally patched binding and remains project-history/reference evidence rather than a supported transport choice.
§Rust version and dependency selection
NBReq supports Rust 1.85 or later and keeps compatible dependency ranges in its
published manifest. Applications choose their dependency versions through
Cargo.lock; the library’s own lockfile is not imposed on downstream consumers.
At the 0.2.1 release, a fresh Rust 1.85 build can select yoke-derive 0.8.3 through
the URL/IDNA/ICU dependency chain and fail with str::from_utf8 not found. That
upstream build-time macro uses an API introduced in Rust 1.87 without declaring
the compiler requirement in its package metadata. There are two routes:
-
Use Rust 1.87 or a newer supported toolchain to supply the missing API.
-
Stay on Rust 1.85 and select the compatible dependency in your application:
cargo +1.85.0 update -p yoke-derive --precise 0.8.2 cargo +1.85.0 build --locked
Run these commands from the application workspace, after it has an NBReq
dependency and a lockfile (cargo +1.85.0 generate-lockfile creates one if needed).
Keep the resulting Cargo.lock under version control. An unrestricted future
cargo update can select 0.8.3 again, so reapply the selection if that happens.
Rust 1.86 has the same missing API; use the same selection with +1.86.0 if that
is your installed toolchain.
The compiler upgrade addresses this known upstream error; future dependency
releases may have their own Rust requirements.
NBReq does not pin yoke-derive for all consumers or change runtime behavior.
Release checks distinguish fresh current-stable graphs from Rust 1.85 graphs
with this explicit compatibility selection, retaining the initial and selected
locks. Revisit the workaround after upstream publishes a compatible correction.
§Platform scope
NBReq 0.3.1 targets Rust 1.85 or later with Rust 2024 edition; see the dependency selection above when using an older compiler. The verified target set is:
| Target | Tested scope |
|---|---|
| Windows x64 MSVC | Windows 10 or later; native HTTP/TLS, DNS, TCP and lifecycle gates |
| Linux x64 GNU | Ubuntu 20.04 ABI baseline; native HTTP/TLS, DNS, TCP and lifecycle gates |
| macOS Intel and Apple Silicon | macOS 15 CI on both architectures, physical Intel macOS 15 and Apple Silicon macOS 26; ordinary default DNS topology, Keychain trust and lifecycle gates |
| Windows x86 MSVC | Additional focused memory/lifecycle and consumer-integration evidence; not a claim of every x64 test on x86 |
Other operating systems, architectures and older macOS versions are not covered by this release’s
support claim. Windows x86 also has focused compatibility evidence under Ubuntu 20.04’s stock
Wine 5.0 (Ubuntu package 5.0-3ubuntu1), using a private Win32 prefix and an app-local ProcessPrng
shim. In that environment, actual portable-trust tests and verified live IMAPS/SMTP STARTTLS
transport probes passed; the live probes explicitly selected BundledMozilla and performed
unauthenticated greetings/capability/quit exchanges. Platform-trust verification still failed.
This is evidence for that explicit configuration, not every Wine/host combination or SMTP message
delivery. Validate the intended deployment and trust mode.
macOS discovery accepts a bounded ordinary default System Configuration view. Supplemental
/etc/resolver entries, split/scoped routing, conflicting primary services and other unrepresented
topologies return Unsupported instead of sending DNS queries to a guessed server. This can reject
Engine construction, including a native-only HTTP consumer; disabling the public Resolver does
not bypass internal DNS discovery. Accepted system configuration changes are rediscovered by the
existing DNS owner. Windows/Linux discovery likewise uses the Engine’s bounded configuration
model; NBReq does not promise every OS resolver extension.
§Buffered HTTP memory controls
Engine body ceilings remain 16 MiB by default. A request can further restrict either ceiling
using max_request_body_bytes and max_response_body_bytes, or the corresponding optional
fields in RequestOptions. None inherits the Engine ceiling; zero allows only an empty body.
These limits follow redirects and apply to total streaming bodies as well as buffered bodies.
They are separate from streaming queue windows. An upload is checked before admission; a reply
is checked at validated framing and during receipt, before buffering an oversized body.
An optional EngineBuilder::max_buffered_body_bytes / EngineConfig::with_max_buffered_body_bytes
caps aggregate retained buffered payload capacity. No aggregate cap is enabled by default.
For example (values are illustrative, not a recommended device profile):
use nbreq::Engine;
let engine = Engine::builder()
.max_buffered_body_bytes(8 * 1024 * 1024)
.build()?;
let response = engine.get("https://example.com/status")
.max_response_body_bytes(1024 * 1024)
.call()?;
// Borrow or explicitly copy response.body(), as before. Response clones share one charge.
let body = response.into_body();
let application_bytes = body.try_into_vec().expect("no other body owner");
engine.shutdown()?;The aggregate scope includes admitted request Vec capacity (also buffered uploads with streamed responses), returned/unread/queued response bodies, spare capacity, transient old and new body allocations during growth, receive-event storage and extracted TLS plaintext. Cleartext buffered uploads queue shared slices of the original allocation, so they need no copied body send buffer. Receive windows are conservatively charged in full even when they also contain HTTP framing. Separately parsed headers and other metadata remain governed by their existing limits. TLS session/record output buffers, socket buffers, stacks, allocator bookkeeping/rounding and application-owned allocations need additional headroom. This is not a process RAM cap.
Known response lengths reserve capacity at the head without allocating it until payload arrives. HEAD/no-body responses do not reserve the advertised representation size. Unknown-length bodies grow in bounded steps, acquiring the replacement’s capacity while the old allocation is still charged. The budget must therefore leave room for staging and growth, not just final body length. There is no full maximum-response reservation for each queued request or quiet long poll.
Insufficient capacity produces ErrorKind::Limit with LimitKind::BufferedBodyBytes, distinct
from RequestBodyBytes / ResponseBodyBytes. NBReq fails the exchange rather than waiting for
other partial replies, and never automatically replays it. A response-side failure may occur
after a POST has taken effect; the error does not imply that retrying is safe.
Completed responses remain charged until the last body owner drops, including after Engine
shutdown. Successful unique try_into_vec transfers the existing allocation into application
ownership and ends its NBReq charge; the memory still exists and must be budgeted by the caller.
Public Response::new and explicit streaming collection create application-owned bodies.
The ledger retains no sockets or workers. engine.metrics().current().reserved_buffered_body_bytes()
reports retained/reserved capacity, and high_water() exposes its observed peak.
Configure concurrent-work admission as well as byte limits. The native defaults are 32 HTTP connection slots, eight per origin and 1,024 accepted HTTP requests. These are ceilings, not allocations made for every slot. Reduce accepted work for an application that can queue it more cheaply elsewhere. Low per-origin connection counts can delay short calls behind long polls; application scheduling should leave room for time-sensitive traffic.
There are three distinct byte controls:
| Control | Charged work |
|---|---|
max_buffered_body_bytes (optional) | Retained/reserved buffered HTTP payload capacity and its charged receive staging |
max_stream_queued_bytes | HTTP streaming response windows |
max_queued_bytes | Shared parent for HTTP streaming response windows, standalone TCP send/receive windows and additional TLS staging reservations |
Per-stream and per-TCP-connection windows also apply. A buffered upload with a streamed response participates in the buffered-body cap as well as its response’s streaming window. These limits do not include all application, TLS, kernel, thread-stack or allocator memory.
§Upgrading to NBReq 0.3.0
Version 0.3.0 introduces finite defaults for common
network operations. Existing "0.2" Cargo requirements stay on the 0.2 line;
select nbreq = "0.3.0" when adopting this release.
§New timeout defaults
Buffered HTTP requests, including the Engine GET/POST convenience calls and
RequestOptions::default(), now allow ten seconds for connection establishment,
thirty seconds without useful I/O progress, and 120 seconds overall. Public DNS
resolution has a thirty-second total deadline. TCP connection establishment has
a ten-second deadline, and pending TCP/TLS output has a thirty-second write
inactivity deadline.
A healthy, quiet TCP/TLS connection stays open. Connected read inactivity remains disabled by default; the write timer is inactive when no accepted output awaits progress. There is no overall TCP/TLS connection lifetime limit.
Fresh StreamRequest builders use the HTTP connect and inactivity defaults but
have no total-duration limit. A quiet event stream or slow upload producer may
still need inactivity_timeout(None). Converting an existing Request into a
StreamRequest preserves all its options, including the buffered request’s
120-second total timeout. Likewise, .options(RequestOptions::default()) replaces
the stream’s complete options with buffered defaults. Configure the options you
intend; conversion and submission never infer whether a value was explicit.
These defaults can end slow requests, long polling and stalled transfers that previously waited indefinitely. Explicitly configured durations still take precedence. Existing duration-based calls compile unchanged.
§Select a duration or disable a timer
HTTP, DNS and TCP timeout setters now accept Duration, Some(Duration) or
None. Omitting a setting uses its default. Passing None explicitly disables
that timer; it never means “inherit the default”. The last setter wins.
For these optional request timers, a zero duration gives a timer no waiting
budget once it is active; it does not disable the timer or necessarily fail in
the builder. Expiry is processed by the Engine, so manual Engines still need
driving. TCP read/write inactivity applies only after connection establishment;
the write clock runs only while accepted output awaits progress, and the read
clock pauses under receive backpressure. TLS retains its separate finite,
nonzero handshake requirement.
To restore the previous unbounded HTTP policy:
use nbreq::Request;
let request = Request::get("https://example.com/")
.connect_timeout(None)
.inactivity_timeout(None)
.total_timeout(None)
.build()?;The Engine GET/POST convenience builders and streaming builders accept the same
three setters. Setting the corresponding public RequestOptions fields to
None has the same effect.
For plain TCP, disable establishment and write inactivity to recover its former defaults; read inactivity is already disabled:
use nbreq::TcpConnectRequest;
let request = TcpConnectRequest::hostname("example.com", 9000)
.connect_timeout(None)
.write_inactivity_timeout(None)
.build()?;For DNS, use ResolveRequest::hostname(name).total_timeout(None). This removes
the operation deadline while retaining the resolver’s existing finite internal
retry budgets. Internal HTTP/TCP lookups use their enclosing connect/total
budgets; they do not gain an additional thirty seconds.
§Direct TLS and STARTTLS
TlsOptions retains its existing finite ten-second establishment deadline and
its Duration setter. Direct TLS uses the earlier of this deadline and the TCP
connect deadline, covering DNS, TCP, handshake and certificate verification.
To allow a longer direct-TLS establishment, raise or disable the TCP connect
deadline as well:
use std::time::Duration;
use nbreq::{TcpConnectRequest, TlsOptions};
let request = TcpConnectRequest::hostname("mail.example.org", 993)
.connect_timeout(None)
.build()?;
let tls = TlsOptions::new("mail.example.org")?
.handshake_timeout(Duration::from_secs(30));An upgrade starts a fresh TLS deadline; it does not reuse the completed TCP
connection’s establishment budget. Established TLS keeps the selected connected
read/write policies. The new None support does not remove the existing finite
TLS handshake requirement.
§Unchanged clock and resource semantics
Operation deadlines start at admission, including time queued inside the Engine. HTTP redirects retain the original total deadline while renewing the existing per-hop connect/inactivity clocks. Useful I/O progress resets inactivity, and response-consumer backpressure pauses it; waiting for an empty streaming upload producer does not pause HTTP inactivity.
wait_for still bounds only a local wait and leaves the underlying operation
live. Manual Engines still require explicit driving to process deadlines.
Timeouts do not impose a hard bound on executing user callbacks or platform
certificate checks during joined shutdown.
Queue sizes, body limits, connection limits, DNS selection/retry policy, TLS verification and dependency requirements are unchanged. See the defaults table for the complete policy, and the 0.2 migration guide for earlier API changes.
§Upgrading to NBReq 0.2.1
Select nbreq = "0.2.1" for the APIs described here. Existing "0.2" requirements permit
0.2.1, but an application’s lockfile controls when it updates; "0.1" stays on the 0.1 line.
§From 0.2.0 to 0.2.1
Existing HTTP, DNS and plain TCP APIs remain available. The additions are verified TLS 1.2/1.3
connections, consuming TCP-to-TLS upgrades, TLS waiters/callbacks, Engine::run_mode() and
explicit Engine trust selection. PendingTlsConnect works with the existing sealed
WaiterTarget and drive_until. TlsFailure::Truncated extends an already non-exhaustive enum;
retain wildcard match arms. Use a minimum of 0.2.1 when calling these new APIs.
Review these behavior changes when upgrading:
- Additional DER roots now pass WebPKI trust-anchor parsing even in platform mode. Certificates an OS previously accepted or ignored differently can fail Engine construction.
- Backends that cannot apply explicit trust settings return
Unsupported. This includes publictest-supportheld/HTTP-only constructors that previously ignored additional roots. Tests using production TLS settings may need an HTTPS fixture or a configuration without unused roots. - Accepted plain TCP send buffers shed spare
Veccapacity, which may allocate or copy. Refused buffers retain their original allocation and bytes; partial blocking sends still return only the unaccepted suffix. - Peer FIN remains EOF when queue pressure changes, so read inactivity does not restart after EOF. Small native receive windows use bounded allocation. These fixes preserve byte-stream semantics while tightening resource behavior.
Platform trust remains the default, including when bundled-roots is enabled. Select
TlsTrust::SuppliedRootsOnly with at least one DER root, or enable bundled-roots and select
TlsTrust::BundledMozilla. Portable modes retain certificate and identity checks but do not
inherit OS enterprise roots, distrust rules or revocation retrieval. There is no automatic
fallback. Update the application lockfile, rebuild and redeploy to refresh bundled roots.
See trust configuration and TLS lifecycle
and runnable TLS examples.
Rust 1.85 remains supported with compatible dependency selection. Fresh graphs
can select upstream yoke-derive 0.8.3, which needs a Rust 1.87 API; older-compiler
applications can select 0.8.2 in their own lockfile without restricting all NBReq
consumers. See the commands and dependency policy.
The following sections describe the earlier changes from 0.1.1 to the 0.2 line.
§Existing HTTP consumers
The explicit Engine / Client / Request APIs, borrowed Response::body() slice, callbacks,
direct waiters, manual drive, streaming, cancellation and consuming shutdown remain available.
HTTP 4xx/5xx remain responses; cancellation, timeout, transport and limit errors remain distinct.
Neither Client handles nor retained response bodies extend the Engine’s network lifetime.
Response::clone() now shares immutable body storage instead of copying its bytes; headers still
clone. Code reading body() works as before. Code requiring independent application storage can
continue to call response.body().to_vec(). Code relying on a clone allocating a fresh body must
make that copy explicit. Consuming access can transfer the original allocation:
use nbreq::Response;
let original = Response::new(200, Vec::new(), b"payload".to_vec());
let retained = original.clone();
let body = original.into_body();
let shared = body.try_into_vec().expect_err("retained still owns the body");
drop(retained);
let bytes = shared.try_into_vec().expect("now uniquely owned");
assert_eq!(bytes, b"payload");An enabled aggregate buffered-body cap remains charged while any response/body owner retains the allocation, including after Engine shutdown. Unique Vec transfer ends the nbreq charge and moves memory responsibility to the application; it does not free that allocation.
§New capabilities
Engine::get/postprovide blocking buffered convenience on a spawned Engine. They share the ordinary pool, limits and lifecycle; no global runtime is created.Engine::resolverprovides public DNS through the default-onresolverfeature. Exact lookup is the default, search expansion is opt-in, and NXDOMAIN/NoData are completed negative answers.Engine::tcp_connectorprovides cancellable cleartext TCP and bounded duplex queues. It shares the native reactor and does not expose raw sockets. Version 0.2.1 adds separate verified TLS connection and upgrade calls without changing the ordinary cleartext calls.Engine::drive_untilaccepts HTTP, DNS and TCP direct waiters through the sealedWaiterTargettrait. Ordinary HTTP calls retain their return type; consumers storing the method as a function item may need to specify the waiter type explicitly.- Per-request body ceilings can tighten Engine limits; an opt-in aggregate buffered-body cap
accounts for retained capacity and staging. Both controls report distinct
LimitKindvalues. - Additional DER CA certificates supplement platform trust for an Engine. Hostname/validity checks remain enabled, and trust changes apply to that Engine’s redirects as well.
- Intel and Apple Silicon macOS join the tested platform set for bounded ordinary-default DNS topology. Richer split/scoped configurations are rejected explicitly.
§Configuration and behavior to review
The default features are now native and resolver. Native-only consumers can disable the
public Resolver while retaining HTTP, TLS, standalone TCP and internal exact-name DNS. A build
with no features compiles portable types but cannot construct a network Engine. test-support
is opt-in test machinery, not a backend. The historical curl pilot remains absent from the crate.
Body defaults remain 16 MiB per request/response, and the aggregate buffered-body cap is disabled
unless configured. Individual limits also apply to streamed totals; stream queue windows govern
buffered chunks separately. Shared max_queued_bytes bounds reserved HTTP-streaming and TCP
windows, while max_buffered_body_bytes covers buffered HTTP storage. Neither is a process-RAM
limit. Application-specific adapters may choose different ceilings and workload-admission policies.
New RequestOptions fields default to inheritance. Construct it with Default and mutate fields,
or use request builders; it remains non-exhaustive. Continue using wildcard arms for public
non-exhaustive errors, completions, modes and policy enums.
Failure to reserve a response body can occur after the server has acted on a POST. Do not treat
LimitKind::BufferedBodyBytes as permission to replay it. Release retained data or reduce newly
admitted work, and use the application’s own idempotency/recovery policy.
TLS handshake workers are lazy and bounded. Request cancellation closes its socket promptly,
but an executing platform certificate check can delay joined shutdown. shutdown_for bounds
callback draining after network shutdown; it is not a deadline for platform verification work.
The bounded internal DNS codec replaces the former general DNS dependency. Private DNS parsing,
address fallback, fragmented response handling, streaming shutdown and package-fixture fixes
are included without adding a second resolver/reactor owner. Existing 0.1.1 adapter-recovery
behavior is retained. macOS’s nbreq-darwin helper is an implementation dependency, like
nbreq-winpoll; consumers should depend on nbreq itself.
§Upgrade check
Compile the application with its intended feature selection and Rust version. Exercise its shutdown order, long polls, callback dispatch, retained responses and any configured limits. For memory-constrained applications, size concurrent work and application-owned allocations alongside nbreq’s caps. The release’s component measurements do not establish a universal 128/256 MB device profile or an end-to-end performance guarantee.
Structs§
- Cancel
OnDrop - Opt-in guard that requests cancellation when dropped.
- Client
- Cheap cloneable command handle issued by an
Engine. - Detached
Callbacks - Observable ownership of a sealed callback domain after timed shutdown.
- Engine
- Unique owner of one lifecycle, resource, and bulk-cancellation domain.
- Engine
Builder - Builder for one independently owned Engine.
- Engine
Config - Backend-neutral Engine configuration.
- Engine
Metrics - A payload-free, approximate snapshot of one Engine’s lifetime activity and pressure.
- Engine
Request Builder - Engine-bound builder for a simple buffered HTTP request.
- Error
- A backend-neutral NBReq error.
- Header
- One owned HTTP header.
- Pending
Request - Accepted request plus a direct terminal-state waiter.
- Pending
Resolve - Accepted public resolution plus a direct terminal-state waiter.
- Pending
TcpConnect - Accepted connect plus a direct terminal-state waiter.
- Pending
TlsConnect - Accepted TLS establishment with a direct terminal-state waiter.
- Request
- An owned, backend-neutral HTTP request.
- Request
Builder - Builder for an owned
Request. - Request
Handle - Engine-bound control handle for one accepted request.
- Request
Id - Opaque request identity, scoped to the Engine that issued it.
- Request
Options - Portable request policy and timeout options.
- Resolve
Handle - Engine-bound control handle for one accepted public resolution.
- Resolve
Request - An owned public hostname-resolution request.
- Resolve
Request Builder - Builder for an owned
ResolveRequest. - Resolve
Response - A completed public resolution, including valid NXDOMAIN and NoData answers.
- Resolved
Address - One address collected by a public resolution.
- Resolver
- Cheap cloneable hostname-resolution handle issued by an
Engine. - Resource
Metrics - Current or historical pressure on the Engine’s bounded resources.
- Response
- An owned, backend-neutral HTTP response.
- Response
Body - Immutable, shared storage for a buffered
Responsebody. - Response
Head - The final HTTP status and headers for a streamed response.
- Response
Reader - The unique body and terminal consumer for one accepted streaming request.
- Shutdown
Error - Failure while irreversibly stopping an Engine or callback domain.
- Stream
Request - A request whose response body will be consumed through the streaming API.
- Stream
Request Builder - Builder for a
StreamRequest. - TcpConnect
Handle - Engine-bound control handle for one accepted connect operation.
- TcpConnect
Request - An owned TCP connect request, shared by plain TCP and direct TLS.
TLS identity and handshake policy are supplied separately through
TlsOptions. - TcpConnect
Request Builder - Builder for an owned
TcpConnectRequest. - TcpConnection
- Unique unsplit cleartext TCP connection.
- TcpConnection
Handle - Cloneable cancellation handle for one live TCP connection.
- TcpConnector
- Cheap cloneable plain TCP and direct TLS connector issued by an
Engine. - TcpReader
- Unique TCP receiving half.
- TcpSend
Error - A failed
TcpConnection::try_send,TcpConnection::send,TcpWriter::try_send, orTcpWriter::sendoperation. - TcpWriter
- Unique TCP sending half.
- TlsConnect
Handle - Independent cancellation handle for a pending TLS connect or live TLS connection.
- TlsConnection
- Unique verified TLS stream. The underlying socket cannot be extracted or downgraded.
- TlsOptions
- TLS peer identity and establishment policy. Certificate verification is always enabled.
- TlsReader
- Read half of a verified standalone TLS stream.
- TlsWriter
- Write half of a verified standalone TLS stream.
- TryPush
Error - A failed
UploadSender::try_pushorUploadSender::pushoperation. - Upload
Body - The Engine-owned receiving half of one streamed request body.
- Upload
Finish Error - Failure while explicitly finishing a unique upload producer.
- Upload
Sender - The caller-owned producer for one streamed request body.
Enums§
- Address
Family - Selects which address families a public resolution collects.
- Address
Order - Combined-family ordering of a collected public resolution.
- Cache
Mode - Cache behaviour for one public resolution.
- Callback
Dispatch - Determines where owned callback jobs are executed.
- Completion
- The canonical terminal outcome of an accepted request.
- DnsFailure
- Payload-free reason attached to a DNS-related transport
Errorwhen known. - Drive
Status - Result of one manual Engine driving pass.
- Error
Kind - Stable high-level error classification.
- Execute
Error - Error returned by the blocking convenience API.
- Http
Backend - Selects the HTTP implementation used by an
Engine. - Limit
Kind - Portable resource category attached to a limit
Error. - Method
- An HTTP method.
- Resolve
Completion - Canonical terminal outcome of an accepted public resolution.
- Resolve
Status - Outcome of a completed DNS exchange, including valid negative answers.
- Resolve
Wait Outcome - Result of a waiter-local public-resolution timeout.
- RunMode
- Determines who progresses an
Engine. - Shutdown
Outcome - Result of a consuming timed Engine shutdown.
- Stream
Error - A terminal request failure, cancellation, or invalid local streaming operation.
- Stream
Read - The result of one nonblocking
ResponseReader::try_readcall. - TcpConnect
Completion - Canonical terminal outcome of an accepted connect.
- TcpConnect
Target - Destination of a TCP connect request, shared by plain TCP and direct TLS.
TLS certificate identity is supplied separately through
TlsOptions. - TcpConnect
Wait Outcome - Result of a waiter-local connect timeout.
- TcpFinish
Error - Failure while finishing a TCP write half.
- TcpFinish
Status - Passive result of
TcpConnection::try_finishorTcpWriter::try_finish. - TcpRead
- Passive read result for one TCP connection or reader.
- TcpSend
Error Kind - Stable reason a TCP send was not fully accepted.
- TcpStream
Error - A terminal TCP stream failure, cancellation, reset, or invalid local operation.
- Timeout
Kind - Portable timeout category attached to a timeout
Error. - TlsConnect
Completion - Canonical outcome of either an immediate TLS connect or a consuming upgrade.
- TlsConnect
Wait Outcome - Result of a timed wait for TLS establishment.
- TlsFailure
- Payload-free reason attached to a TLS-related transport
Errorwhen known. - TlsTrust
- Selects the certificate trust used for verified TLS throughout an Engine.
- TlsVerification
- Controls server-certificate and hostname verification for HTTPS requests.
- Transport
Stage - Portable transport stage attached to a transport
Error. - TryPush
Error Kind - Why a nonblocking streamed-upload push did not accept its chunk.
- Upload
Finish Error Kind - Why
UploadSender::finishcould not finish its body. - Wait
Outcome - Result of a waiter-local timeout.
Traits§
- Waiter
Target - A finite accepted operation that a manual
Enginecan drive to one terminal.