nano-get
nano-get is a tiny HTTP/1.1 client for GET and HEAD.
- Default build: zero external dependencies.
- HTTPS: enable the
httpsfeature to use the system OpenSSL library through the optionalopensslcrate. - API style: simple helper functions for common calls, plus typed
Request/ResponseandClient/SessionAPIs when you need more control. - Edition: Rust
2021. - MSRV: Rust
1.71.0. - CI: tested on Rust
1.71.0and lateststable.
Installation
HTTP only:
[]
= "0.3.0"
HTTP + HTTPS:
[]
= { = "0.3.0", = ["https"] }
Examples
The repository includes a graduated set of runnable Cargo examples under
examples/, starting with simple helper functions and ending with advanced
client configuration.
Representative commands:
cargo run --example simple-getcargo run --example request-buildercargo run --example advanced-client --features https
Simple API
The get helper is the main ergonomic entry point. It auto-follows redirects and returns the body as UTF-8 text.
If you need raw bytes instead of text:
For HEAD:
HTTPS
With the https feature enabled, unified helpers route to TLS automatically:
You can also force the protocol-specific helpers:
nano_get::get_httpnano_get::get_http_bytesnano_get::head_httpnano_get::get_httpsnano_get::get_https_bytesnano_get::head_https
Without the https feature, attempting to request an https:// URL returns a typed NanoGetError::HttpsFeatureRequired.
Advanced API
Use Request when you need custom headers or manual redirect handling.
use ;
Use Client when you need connection reuse, caching, or proxy support.
use ;
Authentication
nano-get exposes both ergonomic helpers for common cases and a generic challenge/response hook
for non-Basic schemes.
Challenge-driven Basic auth:
use ;
Challenge-driven Basic proxy auth:
use ;
Preemptive Basic auth is also available when you know the server or proxy requires credentials on the first request:
ClientBuilder::preemptive_basic_authClientBuilder::preemptive_basic_proxy_auth
Manual request-level overrides:
Request::authorizationRequest::proxy_authorizationRequest::basic_authRequest::proxy_basic_auth
For non-Basic schemes, install a custom AuthHandler with ClientBuilder::auth_handler or
ClientBuilder::proxy_auth_handler.
Use Session when you want a dedicated persistent connection or pipelined safe requests:
use ;
Response exposes:
versionstatus_codereason_phrase- ordered
headers - optional
trailers - raw
body: Vec<u8> - helper methods like
header,trailer,body_text, andheaders_named
Redirects
- Helper functions auto-follow redirects up to
10hops. Request::execute()does not follow redirects unless you opt in withRedirectPolicy::follow(...).- Supported redirect statuses:
301,302,303,307,308.
Origin Authorization headers are preserved only for same-scheme, same-host, same-port redirects.
Proxy-Authorization is scoped to the configured proxy and is never forwarded to the origin.
Migration Notes
- Redirect
Locationvalues with ascheme:prefix are now interpreted as absolute URI references. Unsupported schemes (for examplefoo:barorftp:...) now fail withNanoGetError::UnsupportedSchemeinstead of being treated as relative paths. - Response parsing now enforces defensive bounds (maximum line length and maximum header count). Oversized status/header lines or excessive header blocks are rejected as malformed.
- Pipelining replay logic now retries unanswered safe requests after abrupt peer disconnects even
when
Connection: closewas not explicitly signaled. - Reused keep-alive connections now retry once on EOF-shaped read failures (stale socket closes) before surfacing an error.
- If a server violates
HEADsemantics by sending body bytes, the connection is now retired before reuse to prevent response-stream desynchronization.
Strict Header Rules
nano-get owns the wire-level headers that are required for RFC-correct request framing and proxy
behavior. These headers are rejected if you try to add them manually:
- Protocol-managed:
Host,Connection,Content-Length,Transfer-Encoding,Trailer,Upgrade - Hop-by-hop:
Keep-Alive,Proxy-Connection,TE
End-to-end auth headers remain available through the explicit request/auth APIs.
Caching
The built-in in-memory cache is opt-in through CacheMode::Memory.
Supported request directives:
max-agemin-freshmax-staleonly-if-cachedno-cacheno-store
Supported response directives:
max-agemust-revalidateproxy-revalidateno-cacheno-storepublicprivate
Additional cache behavior:
ETagandLast-Modifiedvalidator revalidationVary-keyed variants- RFC-style
Agehandling in freshness calculations HEADmetadata refresh for cachedGETresponses- cacheable
206 Partial Contentstorage and safe partial combination - conservative auth-aware caching rules
Deliberate exclusions:
- compression
- cookies
- async I/O
- HTTP/2 and HTTP/3
Compliance
The crate’s compliance claim covers all client-applicable RFC 9110, RFC 9111, and RFC 9112
requirements for an HTTP/1.1 GET/HEAD user agent, within the documented claim boundary.
Auditable artifacts:
- docs/compliance/http11-get-head-rfc-matrix.md
- docs/compliance/http11-get-head-requirement-test-index.md
Local compliance/coverage commands:
cargo llvm-cov clean --workspacecargo llvm-cov --workspace --no-default-features --features http --lcov --output-path /tmp/http_cov.infopython3 tools/check_line_coverage.py --lcov /tmp/http_cov.info --root . --require 95cargo llvm-cov clean --workspacecargo llvm-cov --workspace --all-features --lcov --output-path /tmp/all_cov.infopython3 tools/check_line_coverage.py --lcov /tmp/all_cov.info --root . --require 95
Notes
nano-getsupportsHTTP/1.0andHTTP/1.1responses.- Supported body framing:
Content-Length,Transfer-Encoding: chunked, and connection-close bodies. - Supports persistent connections, request pipelining for
GET/HEAD, in-memory caching, direct HTTP, direct HTTPS, HTTP proxies, HTTPS over HTTPCONNECTproxies,401/407auth challenge parsing, and Basic auth helpers. - Conditional request helpers are available on
Requestfor validators and ranges. - Compression, cookies, async, HTTP/2, and non-core auth scheme implementations are intentionally out of scope for
0.3.0.