Skip to content

docs(design): SSH transport async followups: default flip, decouple delta, backpressure (#1890, #1891, #1892)#4272

Merged
oferchen merged 1 commit into
masterfrom
docs/ssh-async-followups-1890
May 17, 2026
Merged

docs(design): SSH transport async followups: default flip, decouple delta, backpressure (#1890, #1891, #1892)#4272
oferchen merged 1 commit into
masterfrom
docs/ssh-async-followups-1890

Conversation

@oferchen
Copy link
Copy Markdown
Owner

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, the OC_RSYNC_SSH_ASYNC=0 escape 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 bounded crossbeam-channel queue. Specifies DemuxedFrame { tag, payload }, the single-FIFO ordering rule for MSG_DATA vs MSG_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=N CLI flag plus OC_RSYNC_SSH_MAX_IN_FLIGHT_BYTES env var, implemented as a tokio::sync::Semaphore at 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 the max(N, MAX_PAYLOAD_LENGTH) floor that prevents single-frame deadlock, and ties queue depth to N / typical_frame_size.

Each doc carries a 5-step impl plan and a trigger-condition section. No code changes.

Test plan

  • CI: workflows (no compile / no test impact; docs-only change).
  • cargo fmt --all --check clean.
  • No references to forbidden terms in the new files.
  • Cross-links between the three docs and back to the umbrella eval resolve.

…, 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 oferchen merged commit 5cec922 into master May 17, 2026
8 checks passed
@oferchen oferchen deleted the docs/ssh-async-followups-1890 branch May 17, 2026 20:45
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 17, 2026
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant