bluenote

A flexible HTTP client library with profile-based configuration support for Rust.

Features

Profile-based configuration: Store connection settings, headers, and authentication in profiles
Multiple authentication methods: Basic auth, custom headers, certificate-based auth
Response decoding: Automatic decompression (gzip, deflate, zstd) and encoding detection
Proxy support: HTTP and HTTPS proxy configuration
TLS configuration: Custom CA certificates and insecure mode support
Clean abstractions: Well-defined traits for building HTTP clients
INI file support: Load profiles from standard INI configuration files

Quick Start

Add this to your Cargo.toml:

[dependencies]
bluenote = { version = "0.1.0", features = ["ini-profiles"] }

Example Usage

Loading a Profile and Making Requests

use bluenote::{HttpClient, IniProfileStore, HttpRequestArgs, UrlPath};
use std::collections::HashMap;

// Define your request
struct MyRequest {
    method: String,
    path: UrlPath,
    body: Option<String>,
    headers: HashMap<String, String>,
}

impl HttpRequestArgs for MyRequest {
    fn method(&self) -> Option<&String> { Some(&self.method) }
    fn url_path(&self) -> Option<&UrlPath> { Some(&self.path) }
    fn body(&self) -> Option<&String> { self.body.as_ref() }
    fn headers(&self) -> &HashMap<String, String> { &self.headers }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load a profile from an INI file
    let store = IniProfileStore::new("profiles.ini");
    let profile = store.get_profile("api")?.unwrap();

    // Create HTTP client with the profile
    let client = HttpClient::new(&profile)?;

    // Create your request
    let request = MyRequest {
        method: "GET".to_string(),
        path: UrlPath::new("/users"),
        body: None,
        headers: HashMap::new(),
    };

    // Make the request
    let response = client.request(&request).await?;
    println!("Status: {}", response.status());
    println!("Body: {}", response.body());

    Ok(())
}

Profile Configuration (INI Format)

Create a profiles.ini file:

[api]
host = https://api.example.com
@content-type = application/json
@accept = application/json
@authorization = Bearer your-token-here

[local]
host = http://localhost:8080
@content-type = application/json
insecure = true

[staging]
host = https://staging-api.example.com
user = username
password = secret
ca_cert = /path/to/cert.pem
proxy = http://proxy.company.com:8080

Configuration Options

Profile settings support:

Connection: host, insecure, ca_cert, proxy
Authentication: user, password (for Basic Auth)
Headers: Prefix with @ (e.g., @authorization, @content-type)
TLS: insecure = true to skip certificate verification
Proxy: proxy = http://proxy-server:port

API Reference

Core Traits

HttpConnectionProfile: Defines connection settings (host, auth, TLS, proxy)
HttpRequestArgs: Defines request parameters (method, URL, body, headers)

Main Types

HttpClient: The main HTTP client for making requests
HttpResponse: Response object with status, headers, and body
IniProfile: Profile implementation for INI-based configuration
IniProfileStore: Manager for loading profiles from INI files

URL and Endpoint Types

Endpoint: Represents a server endpoint (scheme, host, port)
Url: Complete URL with endpoint and path
UrlPath: URL path component with query parameters

Response Decoding

The library automatically handles:

Compression: gzip, deflate, zstd decompression
Encoding: UTF-8, Latin-1, and other character encodings
JSON parsing: Automatic JSON deserialization when appropriate
Error handling: Graceful fallbacks for malformed content

Cargo Features

ini-profiles (default): Enable INI file profile support
json-profiles: Enable JSON profile configuration (future feature)

License

Licensed under the Elastic License 2.0. See LICENSE file for details.

Contributing

This library is extracted from the blueline HTTP client project. Contributions are welcome! Please open issues and pull requests on the main repository.

bluenote 0.1.0