Skip to main content

Crate nbreq

Crate nbreq 

Source
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.

SettingDefaultOverride
Buffered HTTP connect, inactivity and total timeouts10, 30 and 120 secondsRequest/builder connect_timeout, inactivity_timeout, total_timeout, or RequestOptions
Fresh streaming HTTP builders10-second connect, 30-second inactivity; no total capThe same three setters on StreamRequestBuilder
Public DNS total timeout30 seconds; internal per-server retries are separateResolveRequestBuilder::total_timeout
Plain TCP connect10 seconds from admission, including DNSTcpConnectRequestBuilder::connect_timeout
Connected TCP/TLS read inactivityNone; idle connections are validTcpConnectRequestBuilder::read_inactivity_timeout
Connected TCP/TLS write inactivity30 seconds while accepted output awaits progressTcpConnectRequestBuilder::write_inactivity_timeout
TLS establishment10 seconds from admission, including immediate-TLS DNS/TCP and certificate verificationTlsOptions::handshake_timeout; an earlier configured connect deadline also applies to direct TLS
TCP/TLS send and receive queue windowsEach inherits the Engine’s 256 KiB per-connection queue ceilingTcpConnectRequestBuilder::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 selectionAvailable behavior
DefaultNative 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-rootsEnables native and optional Mozilla roots; explicitly select TlsTrust::BundledMozilla to use them; default trust remains platform
No featuresPortable configuration/HTTP/TCP types compile; public Resolver is absent and Engine construction returns Unsupported
test-supportAdditional 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:

TargetTested scope
Windows x64 MSVCWindows 10 or later; native HTTP/TLS, DNS, TCP and lifecycle gates
Linux x64 GNUUbuntu 20.04 ABI baseline; native HTTP/TLS, DNS, TCP and lifecycle gates
macOS Intel and Apple SiliconmacOS 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 MSVCAdditional 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:

ControlCharged work
max_buffered_body_bytes (optional)Retained/reserved buffered HTTP payload capacity and its charged receive staging
max_stream_queued_bytesHTTP streaming response windows
max_queued_bytesShared 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 public test-support held/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 Vec capacity, 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 / post provide blocking buffered convenience on a spawned Engine. They share the ordinary pool, limits and lifecycle; no global runtime is created.
  • Engine::resolver provides public DNS through the default-on resolver feature. Exact lookup is the default, search expansion is opt-in, and NXDOMAIN/NoData are completed negative answers.
  • Engine::tcp_connector provides 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_until accepts HTTP, DNS and TCP direct waiters through the sealed WaiterTarget trait. 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 LimitKind values.
  • 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§

CancelOnDrop
Opt-in guard that requests cancellation when dropped.
Client
Cheap cloneable command handle issued by an Engine.
DetachedCallbacks
Observable ownership of a sealed callback domain after timed shutdown.
Engine
Unique owner of one lifecycle, resource, and bulk-cancellation domain.
EngineBuilder
Builder for one independently owned Engine.
EngineConfig
Backend-neutral Engine configuration.
EngineMetrics
A payload-free, approximate snapshot of one Engine’s lifetime activity and pressure.
EngineRequestBuilder
Engine-bound builder for a simple buffered HTTP request.
Error
A backend-neutral NBReq error.
Header
One owned HTTP header.
PendingRequest
Accepted request plus a direct terminal-state waiter.
PendingResolve
Accepted public resolution plus a direct terminal-state waiter.
PendingTcpConnect
Accepted connect plus a direct terminal-state waiter.
PendingTlsConnect
Accepted TLS establishment with a direct terminal-state waiter.
Request
An owned, backend-neutral HTTP request.
RequestBuilder
Builder for an owned Request.
RequestHandle
Engine-bound control handle for one accepted request.
RequestId
Opaque request identity, scoped to the Engine that issued it.
RequestOptions
Portable request policy and timeout options.
ResolveHandle
Engine-bound control handle for one accepted public resolution.
ResolveRequest
An owned public hostname-resolution request.
ResolveRequestBuilder
Builder for an owned ResolveRequest.
ResolveResponse
A completed public resolution, including valid NXDOMAIN and NoData answers.
ResolvedAddress
One address collected by a public resolution.
Resolver
Cheap cloneable hostname-resolution handle issued by an Engine.
ResourceMetrics
Current or historical pressure on the Engine’s bounded resources.
Response
An owned, backend-neutral HTTP response.
ResponseBody
Immutable, shared storage for a buffered Response body.
ResponseHead
The final HTTP status and headers for a streamed response.
ResponseReader
The unique body and terminal consumer for one accepted streaming request.
ShutdownError
Failure while irreversibly stopping an Engine or callback domain.
StreamRequest
A request whose response body will be consumed through the streaming API.
StreamRequestBuilder
Builder for a StreamRequest.
TcpConnectHandle
Engine-bound control handle for one accepted connect operation.
TcpConnectRequest
An owned TCP connect request, shared by plain TCP and direct TLS. TLS identity and handshake policy are supplied separately through TlsOptions.
TcpConnectRequestBuilder
Builder for an owned TcpConnectRequest.
TcpConnection
Unique unsplit cleartext TCP connection.
TcpConnectionHandle
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.
TcpSendError
A failed TcpConnection::try_send, TcpConnection::send, TcpWriter::try_send, or TcpWriter::send operation.
TcpWriter
Unique TCP sending half.
TlsConnectHandle
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.
TryPushError
A failed UploadSender::try_push or UploadSender::push operation.
UploadBody
The Engine-owned receiving half of one streamed request body.
UploadFinishError
Failure while explicitly finishing a unique upload producer.
UploadSender
The caller-owned producer for one streamed request body.

Enums§

AddressFamily
Selects which address families a public resolution collects.
AddressOrder
Combined-family ordering of a collected public resolution.
CacheMode
Cache behaviour for one public resolution.
CallbackDispatch
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 Error when known.
DriveStatus
Result of one manual Engine driving pass.
ErrorKind
Stable high-level error classification.
ExecuteError
Error returned by the blocking convenience API.
HttpBackend
Selects the HTTP implementation used by an Engine.
LimitKind
Portable resource category attached to a limit Error.
Method
An HTTP method.
ResolveCompletion
Canonical terminal outcome of an accepted public resolution.
ResolveStatus
Outcome of a completed DNS exchange, including valid negative answers.
ResolveWaitOutcome
Result of a waiter-local public-resolution timeout.
RunMode
Determines who progresses an Engine.
ShutdownOutcome
Result of a consuming timed Engine shutdown.
StreamError
A terminal request failure, cancellation, or invalid local streaming operation.
StreamRead
The result of one nonblocking ResponseReader::try_read call.
TcpConnectCompletion
Canonical terminal outcome of an accepted connect.
TcpConnectTarget
Destination of a TCP connect request, shared by plain TCP and direct TLS. TLS certificate identity is supplied separately through TlsOptions.
TcpConnectWaitOutcome
Result of a waiter-local connect timeout.
TcpFinishError
Failure while finishing a TCP write half.
TcpFinishStatus
Passive result of TcpConnection::try_finish or TcpWriter::try_finish.
TcpRead
Passive read result for one TCP connection or reader.
TcpSendErrorKind
Stable reason a TCP send was not fully accepted.
TcpStreamError
A terminal TCP stream failure, cancellation, reset, or invalid local operation.
TimeoutKind
Portable timeout category attached to a timeout Error.
TlsConnectCompletion
Canonical outcome of either an immediate TLS connect or a consuming upgrade.
TlsConnectWaitOutcome
Result of a timed wait for TLS establishment.
TlsFailure
Payload-free reason attached to a TLS-related transport Error when known.
TlsTrust
Selects the certificate trust used for verified TLS throughout an Engine.
TlsVerification
Controls server-certificate and hostname verification for HTTPS requests.
TransportStage
Portable transport stage attached to a transport Error.
TryPushErrorKind
Why a nonblocking streamed-upload push did not accept its chunk.
UploadFinishErrorKind
Why UploadSender::finish could not finish its body.
WaitOutcome
Result of a waiter-local timeout.

Traits§

WaiterTarget
A finite accepted operation that a manual Engine can drive to one terminal.