docs(rsync_io): evaluate socketpair vs stdio pipes for SSH subprocess#3438
Merged
Conversation
…#1686, #1689) Adds docs/audits/ssh-socketpair-vs-pipes.md comparing oc-rsync's current two-pipe SSH stdio model against upstream rsync 3.4.1's socketpair-based wire (pipe.c::piped_child, util1.c::fd_pair). Documents trade-offs, cross-platform impact (Unix socketpair, Windows pipe fallback), six findings, and a phased migration plan. The auxiliary stderr channel already uses socketpair on Unix; this audit recommends extending the same pattern to the wire.
github-actions
Bot
added
the
documentation
oferchen
added a commit
that referenced
this pull request
May 1, 2026
…#1686, #1689) (#3438) Adds docs/audits/ssh-socketpair-vs-pipes.md comparing oc-rsync's current two-pipe SSH stdio model against upstream rsync 3.4.1's socketpair-based wire (pipe.c::piped_child, util1.c::fd_pair). Documents trade-offs, cross-platform impact (Unix socketpair, Windows pipe fallback), six findings, and a phased migration plan. The auxiliary stderr channel already uses socketpair on Unix; this audit recommends extending the same pattern to the wire.
8 tasks
oferchen
added a commit
that referenced
this pull request
May 1, 2026
…nsport (#1938) (#3525) Formalizes the SSH stdio transport audit at docs/audits/ssh-socketpair-vs-pipes.md under tracker #1938, consolidating prior #1686 working notes (PR #3438), the io_uring boundary documented for #1858 (PR #3418), and the stderr socketpair shipped under #1689 (PR #3383). Restructures the document into the formal seven-section layout (summary, upstream reference, current implementation, trade-offs, decision matrix, recommendation, implementation notes) plus findings and references. Recommends keeping anonymous pipes for the SSH wire and not pursuing the socketpair migration: splice(2) and vmsplice(2) require a pipe end, the zero-copy plan in #1860 depends on that, and the unified-FD argument is subsumed by the async-transport refactor (#2068, #1655). Closes #1687 (prototype socketpair wire) as do-not-implement and #1902 (verify wire claim against rsync_io source) as verified. Citations were re-checked against worktree source: builder.rs:300-301 (Stdio::piped on the wire), aux_channel.rs:263-285 (UnixStream::pair for stderr, Unix only), connection.rs:30-39 (SshConnection struct), mod.rs:57-75 (io_uring boundary). Upstream evidence verified against target/interop/upstream-src/rsync-3.4.1/: pipe.c:48-97 (piped_child), util1.c:74-96 (fd_pair), main.c:504-663 (do_cmd dispatch), clientserver.c:116-148 (daemon TCP wire), socket.c:736-846 (sock_exec test escape).
oferchen
added a commit
that referenced
this pull request
May 5, 2026
…#1686, #1689) (#3438) Adds docs/audits/ssh-socketpair-vs-pipes.md comparing oc-rsync's current two-pipe SSH stdio model against upstream rsync 3.4.1's socketpair-based wire (pipe.c::piped_child, util1.c::fd_pair). Documents trade-offs, cross-platform impact (Unix socketpair, Windows pipe fallback), six findings, and a phased migration plan. The auxiliary stderr channel already uses socketpair on Unix; this audit recommends extending the same pattern to the wire.
oferchen
added a commit
that referenced
this pull request
May 5, 2026
…nsport (#1938) (#3525) Formalizes the SSH stdio transport audit at docs/audits/ssh-socketpair-vs-pipes.md under tracker #1938, consolidating prior #1686 working notes (PR #3438), the io_uring boundary documented for #1858 (PR #3418), and the stderr socketpair shipped under #1689 (PR #3383). Restructures the document into the formal seven-section layout (summary, upstream reference, current implementation, trade-offs, decision matrix, recommendation, implementation notes) plus findings and references. Recommends keeping anonymous pipes for the SSH wire and not pursuing the socketpair migration: splice(2) and vmsplice(2) require a pipe end, the zero-copy plan in #1860 depends on that, and the unified-FD argument is subsumed by the async-transport refactor (#2068, #1655). Closes #1687 (prototype socketpair wire) as do-not-implement and #1902 (verify wire claim against rsync_io source) as verified. Citations were re-checked against worktree source: builder.rs:300-301 (Stdio::piped on the wire), aux_channel.rs:263-285 (UnixStream::pair for stderr, Unix only), connection.rs:30-39 (SshConnection struct), mod.rs:57-75 (io_uring boundary). Upstream evidence verified against target/interop/upstream-src/rsync-3.4.1/: pipe.c:48-97 (piped_child), util1.c:74-96 (fd_pair), main.c:504-663 (do_cmd dispatch), clientserver.c:116-148 (daemon TCP wire), socket.c:736-846 (sock_exec test escape).
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
1 participant
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
docs/audits/ssh-socketpair-vs-pipes.md(tasks Fix missing imports in daemon tests #1686 + Add integration tests for core client flows #1689).(
crates/rsync_io/src/ssh/builder.rs:280-282) against upstreamrsync 3.4.1's socketpair wire (
pipe.c::piped_child,util1.c::fd_pair, with pipe fallback whenHAVE_SOCKETPAIRisundefined).
O_NONBLOCKon stdio, no shared poll registration, half-close limits, mixed
IPC primitives across stderr vs wire, multiplex-vs-stderr
boundary) and a three-phase migration plan: socketpair-backed
wire on Unix with Windows pipe fallback, unified-FD event loop
integration, and
shutdown(SHUT_WR)-based half-close.aux_channel.rs:264-291) isalready in place; the audit recommends keeping it and extending
the same factory pattern to the wire. No
SO_PASSCREDor thirdsocketpair needed - upstream multiplexes remote-rsync diagnostics
as
MSG_*envelopes on the wire (io.c::send_msg).Test plan
docs/audits/*.mdstyle).