Crate oneio 

Unified I/O for compressed files from any source.

OneIO provides a single interface for reading and writing files with any compression format, from local disk or remote locations (HTTP, FTP, S3).

Quick Start

[dependencies]
oneio = "0.20"

use oneio;

// Read a remote compressed file
let content = oneio::read_to_string("https://example.com/data.txt.gz")?;

Feature Selection

Enable only what you need:

Feature	Description
gz	Gzip compression
bz	Bzip2 compression
lz	LZ4 compression
xz	XZ compression
zstd	Zstandard compression
http	HTTP/HTTPS support
ftp	FTP support
s3	S3-compatible storage
async	Async I/O support
json	JSON deserialization
digest	SHA256 hashing
cli	Command-line tool

Example: Minimal setup for local files

[dependencies]
oneio = { version = "0.20", default-features = false, features = ["gz"] }

Example: HTTPS with custom TLS for corporate proxies

[dependencies]
oneio = { version = "0.20", default-features = false, features = ["http", "native-tls", "gz"] }

Core API

Reading

// Read entire file to string
let content = oneio::read_to_string("data.txt")?;

// Read lines
for line in oneio::read_lines("data.txt")? {
    println!("{}", line?);
}

// Get a reader for streaming
let mut reader = oneio::get_reader("data.txt.gz")?;

Writing

use std::io::Write;

let mut writer = oneio::get_writer("output.txt.gz")?;
writer.write_all(b"Hello")?;
// Compression finalized on drop

Reusable Client

For multiple requests with shared configuration:

use oneio::OneIo;

let client = OneIo::builder()
    .header_str("Authorization", "Bearer token")
    .timeout(std::time::Duration::from_secs(30))
    .build()?;

let data1 = client.read_to_string("https://api.example.com/1.json")?;
let data2 = client.read_to_string("https://api.example.com/2.json")?;

Compression

Automatic detection by file extension:

Extension	Algorithm
.gz	Gzip
.bz2	Bzip2
.lz4	LZ4
.xz	XZ
.zst	Zstandard

Override detection for URLs with query parameters:

use oneio::OneIo;

let client = OneIo::new()?;
let reader = client.get_reader_with_type(
    "https://api.example.com/data?format=gz",
    "gz"
)?;

Protocols

• Local: /path/to/file.txt
• HTTP/HTTPS: https://example.com/file.txt.gz
• FTP: ftp://ftp.example.com/file.txt (requires ftp feature)
• S3: s3://bucket/key (requires s3 feature)

Async API

Enable the async feature:

let content = oneio::read_to_string_async("https://example.com/data.txt").await?;

Async compression support: gz, bz, zstd LZ4 and XZ return NotSupported error.

Error Handling

use oneio::OneIoError;

match oneio::get_reader("file.txt") {
    Ok(reader) => { /* ... */ }
    Err(OneIoError::Io(e)) => { /* filesystem error */ }
    Err(OneIoError::Network(e)) => { /* network error */ }
    Err(OneIoError::NotSupported(msg)) => { /* feature not enabled */ }
    _ => { /* future error variants */ }
}

Environment Variables

• ONEIO_ACCEPT_INVALID_CERTS=true - Accept invalid TLS certificates (development only)
• ONEIO_CA_BUNDLE=/path/to/ca.pem - Add custom CA certificate to trust store

TLS and Corporate Proxies

For environments with custom TLS certificates (Cloudflare WARP, corporate proxies):

1. Use native-tls feature to use the OS trust store:

   features = ["http", "native-tls"]

2. Or add certificates programmatically:

   let client = OneIo::builder()
       .add_root_certificate_pem(&std::fs::read("ca.pem")?)?
       .build()?;

3. Or via environment variable:

   export ONEIO_CA_BUNDLE=/path/to/ca.pem

Modules

crypto

Crypto provider initialization for rustls.

Structs

OneIo

Reusable OneIO client for applying request configuration across multiple operations.

OneIoBuilder

Builder for [OneIo], modeled after reqwest’s client builder API.

Enums

OneIoError

Error type for OneIO operations.

Functions

download

Downloads a remote resource to a local path.

exists

Checks whether a local or remote path exists.

get_cache_reader

Creates a reader backed by a local cache file.

get_reader

Gets a reader for the given file path.

get_writer

Returns a writer for the given file path with the corresponding compression.

read_lines

Returns an iterator over lines from the provided path.

read_to_string

Reads the full contents of a file or URL into a string.