nbreq 0.3.1

Runtime-independent cancellable HTTP client
Documentation

NBReq

HTTP, DNS and TCP for Rust applications that need concurrent networking, prompt cancellation and control over resource use. Start with a blocking request, submit work to a background engine, or drive networking from your own event loop. No async runtime required.

Highlights

  • Simple blocking HTTP requests for ordinary use, with callbacks, direct waiters, streaming uploads, and streaming responses for advanced scenarios.
  • Prompt cancellation across DNS, connection, TLS, upload, and download work. Shutdown closes sockets before joining owned workers; an executing platform certificate check may delay completion.
  • Run networking on an owned background thread, or drive it manually from a single thread.
  • No Tokio or other async runtime required.
  • Bounded queues, resource limits, connection pooling, structured errors, and deterministic joined shutdown.
  • Rust-native HTTP/1.1 and TLS on Windows, Linux, and Intel/Apple Silicon macOS.
  • Public DNS resolution, plain TCP, verified direct TLS and STARTTLS upgrades using the same Engine ownership and shutdown.
  • Platform certificate trust by default, with explicit private-root-only or bundled Mozilla trust.
  • Shared buffered responses, optional consuming buffer transfer, and opt-in retained-body limits.
  • Sensible operation deadlines, with explicit overrides and None opt-outs; quiet established TCP/TLS connections stay open.

Start with a GET

Requires Rust 1.85 or newer; Rust 1.85/1.86 may need the documented dependency selection. These examples target NBReq 0.3.1.

[dependencies]
nbreq = "0.3.1"
use nbreq::Engine;

let engine = Engine::builder().build()?;
let response = engine
    .get("https://httpbin.org/get")
    .call()?;

println!("HTTP {}", response.status());
println!("{}", String::from_utf8_lossy(response.body()));
engine.shutdown()?;

The snippets use ? inside a function returning Result. For a complete program, start with A01: blocking GET, then try A02: blocking POST.

Common operations have finite timeout defaults. Pass a duration to override a timer or None to disable it. Quiet established TCP/TLS connections have no default read-inactivity deadline. See timeout and queue defaults.

More control when you need it

  • Choose how to run. Blocking calls, nonblocking submission and callbacks share the same request path. Manual driving lets an existing application loop own network progress.
  • Own the lifecycle. One Engine owns network work, connection pools and workers. Cheap Client handles let other parts of your application submit requests. Explicit shutdown cancels outstanding work and joins the owned workers.
  • Bound your workload. Configure connection and request limits, body budgets and queue sizes. Stream larger bodies incrementally; share buffered responses or take their allocation without copying when uniquely owned. Memory controls and A10: memory limits explain the choices.
  • Choose certificate trust. HTTPS and standalone TLS use platform trust by default. Applications can add private CA roots or explicitly select portable verification with supplied roots only or a Mozilla bundle. Trust selection explains the feature and configuration choices.

Keep an Engine for the lifetime of a service so requests can reuse its connections and DNS cache. The following snippets each assume a running, spawned engine.

Cancel outstanding work

use nbreq::{Completion, Request};

let pending = engine.client().submit(
    Request::get("https://httpbin.org/get")
        .build()?,
)?;

// The application can do other work, then decide it no longer needs the request.
pending.handle().cancel()?;
match pending.wait() {
    Completion::Cancelled => println!("Request cancelled"),
    other => println!("Request finished before cancellation: {other:?}"),
}

Check the terminal result: completion can win a race with cancellation. Use engine.cancel_all() to cancel all outstanding work while keeping the Engine available for new requests. A07: cancellation uses a local server to demonstrate and verify Cancelled after the server has received the request.

Resolve a hostname

use nbreq::ResolveRequest;

let answer = engine.resolver().execute(
    ResolveRequest::hostname("example.com")
        .build()?,
)?;

println!("DNS {:?}", answer.status());
for address in answer.addresses() {
    println!("{}", address.address());
}

Choose address families, ordering, caching and search-suffix behavior when needed. DNS also supports nonblocking submission, callbacks, cancellation and manual driving. See the DNS examples.

Exchange bytes over TCP

With an echo server listening on 127.0.0.1:9000:

use nbreq::TcpConnectRequest;

let request = TcpConnectRequest::literal("127.0.0.1:9000".parse()?)
    .build()?;
let mut connection = engine.tcp_connector().execute(request)?;

connection.send(b"hello\n".to_vec())?;
connection.finish()?; // Half-close our output; keep reading the reply.
let mut buffer = [0_u8; 256];
while let Some(count) = connection.read(&mut buffer)? {
    println!("Received {count} bytes");
}

Quiet established connections stay open by default. TCP supports hostname connections, separate reader/writer halves, cancellation, bounded queues and nonblocking I/O. The TCP examples start their own local echo server, so you can run them without setting one up.

For immediate TLS, pass the request and TlsOptions to execute_tls; for a negotiated upgrade, consume the unsplit plain connection with into_tls. Both return a verified TlsConnection. Try C04: direct TLS and C05: TCP-to-TLS upgrade, which run local verified peers, then read the TCP TLS guide. Enabling bundled-roots does not select it automatically: the Engine must explicitly use TlsTrust::BundledMozilla. Platform trust remains the default.

Learn more

  • Getting started: request options, streaming, manual driving, memory controls, error handling and embedding in GUI/FFI applications.
  • Runnable examples: A HTTP, B DNS, C TCP; simplest first.
  • Migration notes: adopting the new defaults or restoring previous timeout behaviour, with links to earlier API migrations.

Scope and configuration

NBReq provides native HTTP/1.1 and HTTPS, DNS resolution, plain TCP and verified TLS 1.2/1.3 connections on Windows, Linux, and Intel/Apple Silicon macOS. TCP/TLS provide byte streams; the application supplies message framing and any STARTTLS negotiation. macOS currently supports the ordinary default DNS configuration; richer split/scoped configurations are rejected explicitly. See the platform scope for tested versions and Wine coverage.

HTTP 4xx/5xx statuses are responses; transport, timeout, limit and cancellation failures are separate outcomes. Resource budgets cover NBReq's specified resources, not total process RAM. Shutdown joins owned work; executing callbacks or platform certificate checks can delay it. The guide covers these contracts in detail.

Default features include HTTP, HTTPS, TCP and the public DNS resolver. HTTP/TCP consumers can use default-features = false, features = ["native"] to omit the public Resolver while retaining internal DNS. See feature selection.

Runtime dependencies use Cargo-compatible version ranges. Your application's lockfile controls updates. Release checks cover the locked graph, fresh consumers on current stable Rust, and the documented compatibility selection on Rust 1.85. See Rust version and dependency selection and dependency policy and security reporting.

Project and license

NBReq is developed by Cave Rock Software Limited, and is licensed under either Apache-2.0 or MIT, at your option. The generated component and dependency license report records the locked release graph.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Copyright (c) 2026 Cave Rock Software Limited.

History

An early prototype used curl as a comparison backend. The supported crate uses NBReq's native implementation; the prototype remains available in Git history.