I/O HTTP

Set of I/O-free Rust coroutines to manage HTTP streams, based on io-stream.

This library allows you to manage HTTP streams using an I/O-agnostic approach, based on 3 concepts:

Coroutine

A coroutine is an I/O-free, resumable and composable state machine that emits I/O requests. A coroutine is considered terminated when it does not emit I/O requests anymore.

See available coroutines at ./src/coroutines.

Runtime

A runtime contains all the I/O logic, and is responsible for processing I/O requests emitted by coroutines.

See available runtimes at io-stream.

Loop

The loop is the glue between coroutines and runtimes. It makes the coroutine progress while allowing runtime to process I/O.

Examples

Send HTTPS request via rustls synchronously

use std::{net::TcpStream, sync::Arc};

use http::Request;
use io_http::v1_1::coroutines::send::{SendHttp, SendHttpResult};
use io_stream::runtimes::std::handle;
use rustls::{ClientConfig, ClientConnection, StreamOwned};
use rustls_platform_verifier::ConfigVerifierExt;

// build TLS stream

let domain = "github.com"
let config = ClientConfig::with_platform_verifier().unwrap();
let server_name = domain.to_string().try_into().unwrap();
let conn = ClientConnection::new(Arc::new(config), server_name).unwrap();
let tcp = TcpStream::connect((domain, 443)).unwrap();
let tls = StreamOwned::new(conn, tcp);

// send request send receive response

let request = Request::get("/").body(vec![]).unwrap();

let mut arg = None;
let mut send = SendHttp::new(request);

let response = loop {
    match send.resume(arg.take()) {
        SendHttpResult::Ok(result) => break result.response,
        SendHttpResult::Err(err) => panic!("{err}"),
        SendHttpResult::Io(io) => arg = Some(handle(&mut stream, io).unwrap()),
    }
};

See complete example at ./examples/send.rs.

More examples

Have a look at projects built on the top of this library:

io-addressbook: Set of I/O-free coroutines to manage contacts
io-oauth: Set of I/O-free Rust coroutines to manage OAuth flows
io-starttls: I/O-free Rust coroutine to upgrade any plain stream to a secure one
Cardamum: CLI to manage contacts
Ortie: CLI to manage OAuth access tokens

License

This project is licensed under either of:

at your option.

Sponsoring

Special thanks to the NLnet foundation and the European Commission that helped the project to receive financial support from various programs:

NGI Assure in 2022
NGI Zero Entrust in 2023
NGI Zero Core in 2024 (still ongoing)

If you appreciate the project, feel free to donate using one of the following providers:

io-http 0.0.2