Calling

A Client submits calls without driving the network, and polls to drive them and collect what finished. It holds up to connections connections, reusing them across calls, and carries up to pipelined_calls calls on each.

use std::time::Duration;
use ucall::*;

let mut client = Client::new(ClientOptions { connections: 4, pipelined_calls: 16, ..Default::default() })?;
for index in 0..64u64 {
    client.submit(ClientCall::post("http://127.0.0.1:8545/infer", vec![index as u8]), index)?;
}
let mut completed: [Completed; 16] = Default::default();
let mut remaining = 64;
while remaining != 0 {
    for done in client.take_completed(&mut completed, Duration::from_secs(1))? {
        match &done.response {
            Ok(response) => println!("call {} answered {}", done.context, response.status_code().0),
            Err(error) => println!("call {} failed: {error}", done.context),
        }
        remaining -= 1;
    }
}

let response = client.get("http://127.0.0.1:8545/health")?;
let keep = response.header("cache-control").map(<[u8]>::to_vec);
drop(client);
println!("{:?} {:?}", response.body(), keep);

submit takes a ClientCall, which owns its URL, header lines, body and security until the call completes, and tags it with a u64 context. A call admitted once completes exactly once, and a client already holding calls unretrieved calls refuses more with Status::Contended. take_completed drives every admitted call and fills a caller-provided buffer with finished ones, waiting up to its timeout for the first, and a zero timeout performs one nonblocking round. get, post, put, delete, patch and call submit one call and poll until it finishes, keeping the completions of other calls they retrieve meanwhile for the next take_completed, which hands those out first. ClientCall::options carries the call’s own ClientCallOptions: a timeout in place of the client’s, retries, redirect hops, security, and the client and server keys.

ClientOptions::max_response_bytes caps what a call buffers, failing it with Status::Overflow past the cap, and ClientOptions::log reports dials that fail every address, refused handshakes and refused redirects. Host names resolve through the library’s own stub resolver, driven by the client’s polling, and connections race the answered addresses as Happy Eyeballs does.

Every received response is a Response, whatever its HTTP status, and only a failed exchange is an Error; Response::fields iterates its header fields as a request’s does. A Response owns its received bytes and is Send, so it stays readable after its Client is dropped and may move to another thread. Dropping the client cancels the calls still in flight and discards completions not yet retrieved.