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 ;
use TcpStream;
# async
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:
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.