docs: refresh README and rustdoc to match the current Tokio API

The README still showed an async-std/Mux::new flow that hasn't existed
since the Tokio rewrite, and lib.rs's quickstart had broken markdown
(##-headings inside a fenced code block) and undefined identifiers.

Rewrite both around the real API (MuxBuilder → connector/acceptor/
worker triple, with examples that compile against the current crate)
and add a configuration section covering keep-alive, idle timeout, and
queue knobs. Add a CI badge to the README pointing at the workflow
that just landed.

Sprinkle one-line rustdoc on the public types and methods that had
none — MuxBuilder + every with_* method, MuxConnector::{connect,
close, get_num_streams}, MuxAcceptor::accept, MuxStream::{is_closed,
get_stream_id}, MuxWorker, StreamIdType, MuxConfig fields, and
mux_connection. cargo doc --no-deps is clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: black-binary

README.md

@@ -1,81 +1,129 @@
 # async-smux
 
-[crates.io](https://crates.io/crates/async_smux)
+[![CI](https://github.com/black-binary/async-smux/actions/workflows/ci.yml/badge.svg)](https://github.com/black-binary/async-smux/actions/workflows/ci.yml)
+[![crates.io](https://img.shields.io/crates/v/async_smux.svg)](https://crates.io/crates/async_smux)
 
-A lightweight asynchronous [smux](https://github.com/xtaci/smux) (Simple MUltipleXing) library for smol/async-std and any async runtime compatible to `futures`.
+A lightweight asynchronous [smux](https://github.com/xtaci/smux) (Simple
+MUltipleXing) library for Tokio. Wraps any `AsyncRead + AsyncWrite +
+Unpin` transport (`TcpStream`, `TlsStream`, …) and lets you spawn many
+bi-directional `MuxStream`s over it — each one looks and behaves like a
+plain TCP stream.
 
 ![img](https://raw.githubusercontent.com/xtaci/smux/master/mux.jpg)
 
-`async-smux` consumes a struct implementing `AsyncRead + AsyncWrite + Unpin + Send`, like `TcpStream` and `TlsStream`, to create a `Mux<T>` struct. And then you may spawn multiple `MuxStream<T>`s (up to 4294967295) over `Mux<T>`, which also implements `AsyncRead + AsyncWrite + Unpin + Send`.
-
-## Benchmark
-
-Here is a simple benchmarking result on my local machine, comparing to the original version smux (written in go).
-
-| Implementation    | Throughput (TCP) | Handshake  |
-| ----------------- | ---------------- | ---------- |
-| smux (go)         | 0.4854 GiB/s     | 17.070 K/s |
-| async-smux (rust) | 1.0550 GiB/s     | 81.774 K/s |
-
-Run `cargo bench` to test it by yourself. Check out `/benches` directory for more details.
-
-## Laziness
-
-No thread or task will be spawned by this library. It just spawns a few `future`s. So it's totally runtime-independent.
+## Quickstart
+
+```rust,ignore
+use async_smux::MuxBuilder;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
+
+#[tokio::main]
+async fn main() {
+    let tcp = TcpStream::connect("127.0.0.1:12345").await.unwrap();
+
+    // build() returns three pieces:
+    //   connector — open new outgoing streams
+    //   acceptor  — receive peer-initiated streams
+    //   worker    — the future that drives I/O; spawn it
+    let (connector, mut acceptor, worker) =
+        MuxBuilder::client().with_connection(tcp).build();
+    tokio::spawn(worker);
+
+    // Outgoing
+    let mut s = connector.connect().unwrap();
+    s.write_all(b"hello").await.unwrap();
+    let mut buf = [0u8; 5];
+    s.read_exact(&mut buf).await.unwrap();
+
+    // Incoming
+    while let Some(mut peer) = acceptor.accept().await {
+        // ...
+    }
+}
+```
 
-`Mux` and `MuxStream` are completely lazy and will DO NOTHING if you don't `poll()` them.
+The server side is identical except for `MuxBuilder::server()`. Client
+and server differ only in stream-id parity (odd vs. even) so two peers
+never collide on locally-allocated ids.
+
+A complete working example is in [`examples/echo.rs`](examples/echo.rs).
+
+## Lifecycle
+
+Three handles share ownership of the connection state:
+
+- **`MuxConnector`** — opens streams. `Clone`-able.
+- **`MuxAcceptor`** — receives peer-initiated streams. Implements
+  `Stream<Item = MuxStream>`.
+- **`MuxWorker`** — the future that drains the underlying transport
+  and dispatches frames. Spawn it with `tokio::spawn(worker)`.
+
+The worker exits when:
+
+- All public handles (connectors + acceptors + streams) are dropped, or
+- `MuxConnector::close().await` is called explicitly, or
+- The peer closes the transport, or
+- A keep-alive timeout fires (if configured).
+
+`close()` performs an orderly shutdown: any frames already accepted by
+`AsyncWrite::poll_write` are drained to the wire before the underlying
+sink is closed. It also works without the worker being polled — useful
+in test setups or sync teardown paths.
+
+## Configuration
+
+```rust,ignore
+use async_smux::MuxBuilder;
+use std::num::{NonZeroU64, NonZeroUsize};
+
+let (connector, acceptor, worker) = MuxBuilder::server()
+    // Send a NOP frame every N seconds to keep the connection alive.
+    .with_keep_alive_interval(NonZeroU64::new(15).unwrap())
+    // If we don't see any frame from the peer for this many seconds,
+    // declare the connection dead and tear everything down.
+    // Defaults to 3 × keep_alive_interval.
+    .with_keep_alive_timeout(NonZeroU64::new(45).unwrap())
+    // Per-stream idle timeout (seconds): close streams with no
+    // recent traffic.
+    .with_idle_timeout(NonZeroU64::new(60).unwrap())
+    // Backpressure thresholds: cap how many frames may sit in the
+    // tx/rx queues before poll_write / poll_read park.
+    .with_max_tx_queue(NonZeroUsize::new(1024).unwrap())
+    .with_max_rx_queue(NonZeroUsize::new(1024).unwrap())
+    .with_connection(connection)
+    .build();
+```
 
-Any polling operation, including `.read()` ,`.write()`, `accept()` and `connect()`, will push `Mux` and `MuxStream` working.
+All of these knobs are optional. Keep-alive and idle timeout are off
+unless explicitly enabled.
 
-## Specification
+## Frame format (smux v1)
 
 ```text
-VERSION(1B) | CMD(1B) | LENGTH(2B) | STREAMID(4B) | DATA(LENGTH)
+VERSION(1B) | CMD(1B) | LENGTH(2B LE) | STREAMID(4B LE) | DATA(LENGTH)
 
 VERSION: 1
-
 CMD:
-    SYN(0)
-    FIN(1)
-    PSH(2)
-    NOP(3)
-
-STREAMID: Randomly chosen number
+    SYN(0)  open stream  (LENGTH must be 0)
+    FIN(1)  close stream (LENGTH must be 0)
+    PSH(2)  payload
+    NOP(3)  keep-alive   (LENGTH must be 0; STREAMID is 0)
 ```
 
-## Example
-
-```rust
-use async_smux::{Mux, MuxConfig};
-use async_std::net::{TcpListener, TcpStream};
-use async_std::prelude::*;
-
-async fn echo_server() {
-    let listener = TcpListener::bind("0.0.0.0:12345").await.unwrap();
-    let (stream, _) = listener.accept().await.unwrap();
-    let mux = Mux::new(stream, MuxConfig::default());
-    loop {
-        let mut mux_stream = mux.accept().await.unwrap();
-        let mut buf = [0u8; 1024];
-        let size = mux_stream.read(&mut buf).await.unwrap();
-        mux_stream.write(&buf[..size]).await.unwrap();
-    }
-}
+Stream id 0 is reserved for NOP; the library never hands it out and
+rejects any peer SYN that uses it.
 
-fn main() {
-    async_std::task::spawn(echo_server());
-    async_std::task::block_on(async {
-        smol::Timer::after(std::time::Duration::from_secs(1)).await;
-        let stream = TcpStream::connect("127.0.0.1:12345").await.unwrap();
-        let mux = Mux::new(stream, MuxConfig::default());
-        for i in 0..100 {
-            let mut mux_stream = mux.connect().await.unwrap();
-            let mut buf = [0u8; 1024];
-            mux_stream.write(b"hello").await.unwrap();
-            let size = mux_stream.read(&mut buf).await.unwrap();
-            let reply = String::from_utf8(buf[..size].to_vec()).unwrap();
-            println!("{}: {}", i, reply);
-        }
-    });
-}
-```
+## Benchmark
+
+| Implementation    | Throughput (TCP) | Handshake  |
+| ----------------- | ---------------- | ---------- |
+| smux (go)         | 0.4854 GiB/s     | 17.070 K/s |
+| async-smux (rust) | 1.0550 GiB/s     | 81.774 K/s |
+
+`benches/bench.rs` uses the unstable `test` crate so it requires a
+nightly toolchain: `cargo +nightly bench`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

src/builder.rs

@@ -1,3 +1,10 @@
+//! Type-state builder for constructing a smux session.
+//!
+//! Start with [`MuxBuilder::client`] or [`MuxBuilder::server`], chain
+//! optional `with_*` calls to configure timeouts and queue limits, then
+//! call `with_connection(...)` followed by `build()` to obtain the
+//! `(MuxConnector, MuxAcceptor, MuxWorker)` triple.
+
 use std::num::{NonZeroU64, NonZeroUsize};
 
 use crate::{
@@ -17,11 +24,15 @@ pub struct WithConfig {
 
 pub struct Begin {}
 
+/// Type-state builder. Move through `Begin → WithConfig → WithConnection`
+/// by calling `client()` / `server()`, optional `with_*`, then
+/// `with_connection(...)`. Finalize with `build()`.
 pub struct MuxBuilder<State> {
     state: State,
 }
 
 impl MuxBuilder<Begin> {
+    /// Configure as a client: locally-allocated stream ids are odd.
     pub fn client() -> MuxBuilder<WithConfig> {
         MuxBuilder {
             state: WithConfig {
@@ -37,6 +48,7 @@ impl MuxBuilder<Begin> {
         }
     }
 
+    /// Configure as a server: locally-allocated stream ids are even.
     pub fn server() -> MuxBuilder<WithConfig> {
         MuxBuilder {
             state: WithConfig {
@@ -54,6 +66,9 @@ impl MuxBuilder<Begin> {
 }
 
 impl MuxBuilder<WithConfig> {
+    /// Send a NOP keep-alive frame every `interval_secs` seconds. When
+    /// set, the dead-peer timeout (see [`Self::with_keep_alive_timeout`])
+    /// also becomes active.
     pub fn with_keep_alive_interval(&mut self, interval_secs: NonZeroU64) -> &mut Self {
         self.state.config.keep_alive_interval = Some(interval_secs);
         self
@@ -67,21 +82,31 @@ impl MuxBuilder<WithConfig> {
         self
     }
 
+    /// Per-stream idle timeout: if a stream sees no traffic for this
+    /// many seconds, it is closed and its handle is reaped.
     pub fn with_idle_timeout(&mut self, timeout_secs: NonZeroU64) -> &mut Self {
         self.state.config.idle_timeout = Some(timeout_secs);
         self
     }
 
+    /// Backpressure threshold for outbound frames. `poll_write` parks
+    /// once a stream's pending tx queue exceeds this value. Defaults
+    /// to 1024.
     pub fn with_max_tx_queue(&mut self, size: NonZeroUsize) -> &mut Self {
         self.state.config.max_tx_queue = size;
         self
     }
 
+    /// Backpressure threshold for inbound frames. The dispatcher parks
+    /// once total pending rx exceeds this value, propagating
+    /// backpressure to the peer's tx side. Defaults to 1024.
     pub fn with_max_rx_queue(&mut self, size: NonZeroUsize) -> &mut Self {
         self.state.config.max_rx_queue = size;
         self
     }
 
+    /// Bind the underlying transport. The transport must implement
+    /// `AsyncRead + AsyncWrite + Unpin`.
     pub fn with_connection<T: TokioConn>(
         &mut self,
         connection: T,
@@ -96,6 +121,10 @@ impl MuxBuilder<WithConfig> {
 }
 
 impl<T: TokioConn> MuxBuilder<WithConnection<T>> {
+    /// Finalize the builder. Returns the three handles that share the
+    /// session: the connector for outgoing streams, the acceptor for
+    /// peer-initiated streams, and the worker future that must be
+    /// polled (e.g. via `tokio::spawn`) to drive I/O.
     pub fn build(self) -> (MuxConnector<T>, MuxAcceptor<T>, MuxWorker<T>) {
         mux_connection(self.state.connection, self.state.config)
     }

src/config.rs

@@ -1,21 +1,35 @@
 use std::num::{NonZeroU64, NonZeroUsize};
 
+/// Parity used for locally-allocated stream ids. Server uses `Even`
+/// (0, 2, 4, …) and client uses `Odd` (1, 3, 5, …) so the two sides
+/// never collide. Stream id 0 is reserved for NOP keep-alive frames
+/// and is never handed out as a real stream id.
 #[derive(Clone, Copy, Debug)]
 pub enum StreamIdType {
     Even = 0,
     Odd = 1,
 }
 
+/// Session configuration. Construct via [`crate::MuxBuilder`] for the
+/// fluent API, or build one directly and pass it to
+/// [`crate::mux_connection`].
 #[derive(Clone, Copy, Debug)]
 pub struct MuxConfig {
+    /// Parity for locally-allocated stream ids. See [`StreamIdType`].
     pub stream_id_type: StreamIdType,
+    /// If set, send a NOP frame this often (seconds) and enable
+    /// dead-peer detection.
     pub keep_alive_interval: Option<NonZeroU64>,
-    /// Maximum gap (seconds) between any two received frames before the
-    /// peer is declared dead and the connection closed. Only consulted
-    /// when `keep_alive_interval` is also set. Defaults to 3 *
-    /// `keep_alive_interval`.
+    /// Maximum gap (seconds) between any two received frames before
+    /// the peer is declared dead and the connection closed. Only
+    /// consulted when `keep_alive_interval` is also set. Defaults to
+    /// 3 × `keep_alive_interval`.
     pub keep_alive_timeout: Option<NonZeroU64>,
+    /// If set, close any stream that sees no traffic for this many
+    /// seconds.
     pub idle_timeout: Option<NonZeroU64>,
+    /// Backpressure threshold for outbound frames per stream.
     pub max_tx_queue: NonZeroUsize,
+    /// Backpressure threshold for inbound frames across the session.
     pub max_rx_queue: NonZeroUsize,
 }