TCP flows

Set of Rust libraries to manage TCP streams, in a I/O-agnostic way.

Motivation

Designing a generic library that works both for the sync world and for any async environment is a real challenge, especially when I/O is involved. This project tries to solve that matter by abstracting I/O away.

Concept

let mut flow = Flow::new()
let conn = Connector::new();

while let Some(io) = flow.next() {
    conn.execute(&mut flow, io)?;
}

let output = flow.take_output()

Flow

The flow is an I/O-free, composable and iterable state machine that emits I/O requests. When an I/O request is processed by a connector, the flow can continue its progression. A flow is considered terminated when it does not emit I/O requests anymore.

See available flows at lib/flow/.

Connector

The I/O connector contains all the I/O logic. It takes input from the flow, executes the requested I/O, then puts the output inside the flow.

See available connectors at io/.

Loop

The loop is the glue between the flow and the I/O connector. It makes the flow progress.

Structure

• tcp-lib: the core lib, including TCP I/O-free models and flows
• tcp-std: a standard, blocking I/O connector for TCP flows

Examples

Write then read synchronously

use tcp_lib::{Read, Write};
use tcp_std::Connector;

let mut conn = Connector::connect("127.0.0.1", 1234).unwrap();

let mut flow = Write::new(b"data".to_vec());

while let Some(io) = flow.next() {
    conn.execute(&mut flow, io).unwrap();
}

let bytes = flow.take_wrote_bytes().unwrap();
println!("wrote bytes: {:?}", String::from_utf8_lossy(&bytes));

let mut flow = Read::new();

while let Some(io) = flow.next() {
    conn.execute(&mut flow, io).unwrap();
}

let output = flow.take_read_bytes().unwrap();
println!("read bytes: {:?}", String::from_utf8_lossy(&output));

See complete example at std/read-write.rs.

cargo run --package tcp-std --example read-write

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: