barehttp

A minimal, explicit HTTP client for Rust

barehttp is a low-level, blocking HTTP client designed for developers who want predictable behavior, full control, and minimal dependencies.

It supports no_std (with alloc), avoids global state, and exposes all network behavior explicitly. There is no async runtime, no built-in TLS—you bring your own via adapters.

Key Features

Minimal and explicit: No global state, no implicit behavior
no_std compatible: Core works with alloc only
Blocking I/O: Simple, predictable execution model
Generic adapters: Custom socket and DNS implementations
Compile-time safety: Typestate enforces correct body usage

Quick Start

use barehttp::response::ResponseExt;

let response = barehttp::get("http://httpbin.org/get")?;
let body = response.text()?;
println!("{}", body);

Using `HttpClient`

For repeated requests or more control, use HttpClient:

use barehttp::HttpClient;
use barehttp::response::ResponseExt;

let mut client = HttpClient::new()?;

let response = client
    .get("http://httpbin.org/get")
    .header("User-Agent", "my-app/1.0")
    .call()?;

println!("Status: {}", response.status_code);
println!("Body: {}", response.text()?);

Configuration

Client behavior is controlled via Config and ConfigBuilder:

use barehttp::HttpClient;
use barehttp::config::ConfigBuilder;
use core::time::Duration;

let config = ConfigBuilder::new()
    .timeout(Duration::from_secs(30))
    .max_redirects(5)
    .user_agent("my-app/2.0")
    .build();

let mut client = HttpClient::with_config(config)?;

let response = client.get("http://httpbin.org/get").call()?;

Making Requests

GET

let mut client = barehttp::HttpClient::new()?;

let response = client.get("http://httpbin.org/get").call()?;

Connection Pooling

Connection pooling is enabled by default for better performance:

use barehttp::config::ConfigBuilder;
use core::time::Duration;

// Customize pooling behavior
let config = ConfigBuilder::new()
    .connection_pooling(true)  // enabled by default
    .max_idle_per_host(5)      // max idle connections per host
    .idle_timeout(Duration::from_secs(90))  // idle timeout
    .build();

let mut client = barehttp::HttpClient::with_config(config)?;

// First request creates a new connection
let resp1 = client.get("http://httpbin.org/get").call()?;

// Second request reuses the pooled connection
let resp2 = client.get("http://httpbin.org/status/200").call()?;

// Disable pooling for one-off requests
let config = ConfigBuilder::new()
    .connection_pooling(false)
    .build();

POST with body

let mut client = barehttp::HttpClient::new()?;

let response = client
    .post("http://httpbin.org/post")
    .header("Content-Type", "application/json")
    .send(br#"{"name":"test"}"#.to_vec())?;

Type-Safe Request Bodies

Request methods enforce body semantics at compile time:

GET, HEAD, DELETE, OPTIONS → methods without body
POST, PUT, PATCH → methods with body

// This won't compile:
let mut client = barehttp::HttpClient::new()?;
client.get("http://example.com").send(vec![])?;

// This compiles - POST requires .send():
let mut client = barehttp::HttpClient::new()?;
client.post("http://example.com").send(b"data".to_vec())?;

Error Handling

All operations return Result<T, barehttp::Error>.

Errors include:

DNS resolution failures
Socket I/O errors
Parse errors
HTTP status errors (4xx/5xx by default)

use barehttp::{Error, HttpClient};

let mut client = HttpClient::new()?;

match client.get("http://httpbin.org/status/404").call() {
    Ok(resp) => println!("Status: {}", resp.status_code),
    Err(Error::HttpStatus(code)) => println!("HTTP error: {}", code),
    Err(e) => println!("Other error: {:?}", e),
}

Automatic HTTP status errors can be disabled via configuration.

Response Helpers

The ResponseExt trait provides helpers for common tasks:

use barehttp::response::ResponseExt;

let mut client = barehttp::HttpClient::new()?;
let response = client.get("http://httpbin.org/get").call()?;

if response.is_success() {
    let text = response.text()?;
    println!("{}", text);
}

Custom Socket and DNS Adapters

barehttp's networking is fully pluggable.

Implement BlockingSocket and DnsResolver traits to provide:

TLS via external libraries
Proxies or tunnels
Embedded or WASM networking
Test mocks

use barehttp::{HttpClient, OsBlockingSocket, OsDnsResolver};

let dns = OsDnsResolver::new();
let mut client: HttpClient<OsBlockingSocket, _> = HttpClient::new_with_adapters(dns);
let response = client.get("http://example.com").call()?;

Implementing Custom Sockets

For embedded systems or custom networking, implement BlockingSocket:

use barehttp::socket::BlockingSocket;
use barehttp::error::SocketError;

struct MyCustomSocket {
    // Your custom implementation
}

impl BlockingSocket for MyCustomSocket {
    fn new() -> Result<Self, SocketError> {
        // Initialize your socket (called by the pool when needed)
        Ok(Self { /* ... */ })
    }
    
    fn connect(&mut self, addr: &SocketAddr<'_>) -> Result<(), SocketError> {
        // Your connection logic
    }
    
    // ... implement other trait methods
}

// Use with HttpClient
let dns = OsDnsResolver::new();
let client: HttpClient<MyCustomSocket, _> = HttpClient::new_with_adapters(dns);

The pool will call MyCustomSocket::new() internally when it needs to create connections.

Design Notes

Blocking I/O keeps the API simple and dependency-free
Connection pooling reuses TCP connections for better performance (configurable)
Generic adapters allow custom socket implementations via trait
Explicit behavior with no hidden global state

barehttp is intended for environments where clarity and control matter more than convenience.

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

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.

barehttp 0.0.1