docs(design): SSH transport async followups: default flip, decouple delta, backpressure (#1890, #1891, #1892)#4272
Merged
Conversation
…, and explicit backpressure Three followup design notes to the umbrella SSH async I/O eval: - ssh-async-default-linux.md (#1890): trigger conditions and 5-step rollout to flip the Linux default from sync to async, with the feature/cfg gate and the OC_RSYNC_SSH_ASYNC=0 escape hatch. - ssh-decouple-delta-from-socket-read.md (#1891): split the SSH read thread from the delta applier via a bounded crossbeam-channel queue; MSG_DATA / MSG_INFO ordering preserved, error propagation via a oneshot channel, queue-depth defaults explained. - ssh-explicit-backpressure-controls.md (#1892): user-facing --ssh-max-in-flight-bytes flag and OC_RSYNC_SSH_MAX_IN_FLIGHT_BYTES env var, implemented as a tokio Semaphore at the multiplex writer and receiver-side queue, default 4 MiB, with the max(N, MAX_PAYLOAD_LENGTH) floor that avoids single-frame deadlock. Each doc lists 5-step impl plan plus trigger conditions and ties back to the umbrella eval's recommendation.
oferchen
added a commit
that referenced
this pull request
May 18, 2026
…, and explicit backpressure (#4272) Three followup design notes to the umbrella SSH async I/O eval: - ssh-async-default-linux.md (#1890): trigger conditions and 5-step rollout to flip the Linux default from sync to async, with the feature/cfg gate and the OC_RSYNC_SSH_ASYNC=0 escape hatch. - ssh-decouple-delta-from-socket-read.md (#1891): split the SSH read thread from the delta applier via a bounded crossbeam-channel queue; MSG_DATA / MSG_INFO ordering preserved, error propagation via a oneshot channel, queue-depth defaults explained. - ssh-explicit-backpressure-controls.md (#1892): user-facing --ssh-max-in-flight-bytes flag and OC_RSYNC_SSH_MAX_IN_FLIGHT_BYTES env var, implemented as a tokio Semaphore at the multiplex writer and receiver-side queue, default 4 MiB, with the max(N, MAX_PAYLOAD_LENGTH) floor that avoids single-frame deadlock. Each doc lists 5-step impl plan plus trigger conditions and ties back to the umbrella eval's recommendation.
oferchen
added a commit
that referenced
this pull request
May 18, 2026
…, and explicit backpressure (#4272) Three followup design notes to the umbrella SSH async I/O eval: - ssh-async-default-linux.md (#1890): trigger conditions and 5-step rollout to flip the Linux default from sync to async, with the feature/cfg gate and the OC_RSYNC_SSH_ASYNC=0 escape hatch. - ssh-decouple-delta-from-socket-read.md (#1891): split the SSH read thread from the delta applier via a bounded crossbeam-channel queue; MSG_DATA / MSG_INFO ordering preserved, error propagation via a oneshot channel, queue-depth defaults explained. - ssh-explicit-backpressure-controls.md (#1892): user-facing --ssh-max-in-flight-bytes flag and OC_RSYNC_SSH_MAX_IN_FLIGHT_BYTES env var, implemented as a tokio Semaphore at the multiplex writer and receiver-side queue, default 4 MiB, with the max(N, MAX_PAYLOAD_LENGTH) floor that avoids single-frame deadlock. Each doc lists 5-step impl plan plus trigger conditions and ties back to the umbrella eval's recommendation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three followup design notes to the umbrella
docs/design/ssh-transport-async-io-eval.md. Each lands a separate concern flagged in that eval but deferred from it. Bundled into one PR for review economy.docs/design/ssh-async-default-linux.md(Handle daemon refusal banners before module list #1890) - when and how to flip the Linux SSH transport default from sync to async. Names the cfg/feature gate, theOC_RSYNC_SSH_ASYNC=0escape hatch, the 5 measurable trigger conditions (async daemon stable, embedded russh parity, SSH-async bench wins, runtime-flavour comparison, bridge-cost probe), and the 5-step rollout with per-step gates.docs/design/ssh-decouple-delta-from-socket-read.md(Handle plaintext daemon MOTD lines before module list ack #1891) - split the SSH socket reader from the delta applier via a boundedcrossbeam-channelqueue. SpecifiesDemuxedFrame { tag, payload }, the single-FIFO ordering rule forMSG_DATAvsMSG_INFO, the oneshot error channel, default queue depth = 4, and the 5-step plan that lands MSG_DATA dispatch before control messages.docs/design/ssh-explicit-backpressure-controls.md(Refine CI workflows and expand packaging coverage #1892) - the--ssh-max-in-flight-bytes=NCLI flag plusOC_RSYNC_SSH_MAX_IN_FLIGHT_BYTESenv var, implemented as atokio::sync::Semaphoreat the multiplex writer and the Handle plaintext daemon MOTD lines before module list ack #1891 reader-to-applier queue. Default 4 MiB to match the typical TCP receive buffer / BDP. Pins themax(N, MAX_PAYLOAD_LENGTH)floor that prevents single-frame deadlock, and ties queue depth toN / typical_frame_size.Each doc carries a 5-step impl plan and a trigger-condition section. No code changes.
Test plan
cargo fmt --all --checkclean.