https://github.com/poseidon-fan/net-mux
network connection multiplexing async lib in rust, built on tokio
https://github.com/poseidon-fan/net-mux
async kcp multiplexing network-programming rust tcp tokio
Last synced: about 2 months ago
JSON representation
network connection multiplexing async lib in rust, built on tokio
- Host: GitHub
- URL: https://github.com/poseidon-fan/net-mux
- Owner: Poseidon-fan
- License: mit
- Created: 2025-09-25T09:12:59.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2026-04-29T09:16:45.000Z (about 2 months ago)
- Last Synced: 2026-04-29T10:35:25.600Z (about 2 months ago)
- Topics: async, kcp, multiplexing, network-programming, rust, tcp, tokio
- Language: Rust
- Homepage:
- Size: 182 KB
- Stars: 140
- Watchers: 6
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
net-mux
[![GitHub][github-badge]][github-url]
[![Crates.io][crates-badge]][crates-url]
[![MIT licensed][mit-badge]][mit-url]
[![Build Status][actions-badge]][actions-url]
[crates-badge]: https://img.shields.io/crates/v/net-mux.svg
[crates-url]: https://crates.io/crates/net-mux
[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
[mit-url]: https://github.com/Poseidon-fan/net-mux/blob/master/LICENSE
[actions-badge]: https://github.com/Poseidon-fan/net-mux/actions/workflows/rust.yaml/badge.svg
[actions-url]: https://github.com/Poseidon-fan/net-mux/actions?branch=master
[github-badge]: https://img.shields.io/badge/github-repo-black?logo=github
[github-url]: https://github.com/Poseidon-fan/net-mux
`net-mux` is an asynchronous connection multiplexing library built on
Tokio. It turns a single ordered, connection-oriented byte stream
(TCP, TLS-over-TCP, KCP, ...) into many concurrent bidirectional logical
streams.
## Features
- **Credit-based per-stream flow control.** Slow consumers do not stall
other streams; total memory is bounded by `max_streams *
initial_stream_window`.
- **Correct `AsyncRead` / `AsyncWrite`.** Large user writes are
transparently fragmented; back-pressure surfaces as `Poll::Pending`.
- **Half-close.** `shutdown()` closes only the write half, mirroring TCP
semantics.
- **Keepalive.** Periodic `Ping` frames with timeout-driven session
shutdown.
- **Graceful close.** `Session::close().await` flushes outstanding frames,
emits a `GoAway`, and joins all background tasks.
- **Lock-free hot paths.** Atomic windows, atomic stream state, single
outbound queue.
See [`docs/architecture.md`](docs/architecture.md) and
[`docs/protocol.md`](docs/protocol.md) for the deeper design notes.
## Quick start
```rust,no_run
use net_mux::{Config, Session};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let conn = TcpStream::connect("127.0.0.1:7777").await?;
let session = Session::client(conn, Config::default());
let mut stream = session.open().await?;
stream.write_all(b"hello\n").await?;
stream.shutdown().await?;
let mut buf = Vec::new();
stream.read_to_end(&mut buf).await?;
println!("{}", String::from_utf8_lossy(&buf));
session.close().await;
Ok(())
}
```
## Examples
### Echo
```sh
$ cargo run --example tcp_server
$ cargo run --example tcp_client
```
The server echoes each line received over a fresh multiplexed stream;
the client reads stdin, opens one stream per line, and prints the reply.
### Reverse tunnel
```sh
$ cargo run --example forward_server # listens on :7777 (transport) and :8001 (proxy)
$ cargo run --example forward_client # connects to :7777, forwards to :8000
```
If you start an HTTP service on `127.0.0.1:8000`
(e.g. `python -m http.server 8000`), it becomes reachable on
`http://127.0.0.1:8001` via the tunnel.
## Configuration
```rust
use net_mux::Config;
use std::time::Duration;
let cfg = Config::builder()
.initial_stream_window(512 * 1024)
.max_frame_size(64 * 1024)
.max_streams(2048)
.keepalive_interval(Some(Duration::from_secs(30)))
.build();
```
## Links
- API [docs][documentation]
- Source [examples][examples]
- Wire-protocol [spec](docs/protocol.md)
[examples]: https://github.com/Poseidon-fan/net-mux/tree/master/examples
[documentation]: https://docs.rs/crate/net-mux/