nerdbank-streams 2.14.411

Tokio implementation of the Nerdbank.Streams multiplexing protocol
Documentation

nerdbank-streams

nerdbank-streams is a Tokio implementation of the Nerdbank.Streams multiplexing protocol. It supports protocol versions 1, 2, and 3 and interoperates with the .NET implementation. For protocol v2 and v3, it supports the additive channel-window growth extensions (control codes 7 and 8). Peers that predate these frames safely retain the fixed-window behavior.

use nerdbank_streams::mxstream::{MultiplexingStream, Options};
use tokio::net::TcpStream;

# async fn example() -> Result<(), nerdbank_streams::mxstream::Error> {
let transport = TcpStream::connect("127.0.0.1:5000").await?;
let mux = MultiplexingStream::connect(transport, Options::default()).await?;
let mut channel = mux.offer_channel("messages", None).await?;
# Ok(())
# }

Channel implements Tokio's AsyncRead and AsyncWrite. Close its write side with AsyncWriteExt::shutdown; use close_read when the application will no longer consume input and the peer may be blocked by flow control. Dropping a Channel closes both directions. When separate tasks own each direction, prefer Channel::into_split: dropping its read half sends ContentReadingCompleted, and dropping or shutting down its write half sends ContentWritingCompleted. Tokio's generic split of a borrowed Channel cannot provide those drop notifications. Protocol v1 cannot notify the peer when only its read half is dropped because it has no read-completion frame.

For resource safety, this crate has a local 64 MiB maximum receive-window policy. It rejects local configuration plus peer offer, acceptance, and window adjustment advertisements above that limit; applications requiring larger windows must use another implementation or split transfers across channels.

Options::max_channel_receive_window limits automatic growth for each channel, while Options::max_total_channel_receive_window is a stream-wide budget for growth beyond each channel's initial window. Their defaults are 16× and 64× the default receive window, respectively. Setting the total budget to zero disables growth without changing normal flow control. Because Tokio's generic AsyncRead trait does not report cancellation of a pending read future, applications that frequently cancel reads may cause a subsequent growth request to be treated as if that read were still pending. The configured per-channel and stream-wide limits continue to bound any resulting buffering.

Development

From this directory:

cargo fmt
cargo build --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
pwsh ../../tools/Pack-Cargo.ps1

The integration tests build and run test/Nerdbank.Streams.Interop.Tests as a stdio peer. Before invoking any dotnet command manually, run .github/Prime-ForCopilot.ps1 from the repository root in the same PowerShell session.

Releasing

The package version is generated by Nerdbank.GitVersioning from the repository version.json; do not edit the placeholder in Cargo.toml. Run pwsh tools/Pack-Cargo.ps1 from the repository root to create a stamped package and verify it locally.

The first release must be published manually with a crates.io API token to create the crate. Then configure crates.io Trusted Publishing for dotnet/Nerdbank.Streams, .github/workflows/release.yml, and the Signing environment. Subsequent GitHub releases publish the exact CI-built artifact using an ephemeral OIDC token, with no stored crates.io token.