Skip to content

docs(comparison): re-verify the two behavioural subsections against 3.5.0 - #7660

Merged
oferchen merged 1 commit into
masterfrom
docs/comparison-350-behavioural-verify
Sep 4, 2026
Merged

docs(comparison): re-verify the two behavioural subsections against 3.5.0#7660
oferchen merged 1 commit into
masterfrom
docs/comparison-350-behavioural-verify

Conversation

@oferchen

@oferchen oferchen commented Sep 4, 2026

Copy link
Copy Markdown
Owner

docs/UPSTREAM_COMPARISON.md is titled "vs upstream rsync 3.5.0" but declared
itself Last verified: 2026-07-22 (against 3.4.4), warning that every section
"touching path resolution, symlink handling, chroot or daemon access control"
still described 3.4.4 with 3.4.4 line offsets.

That warning was broader than the document's contents. Grepping those four
topics returns 13 lines, and only two subsections make behavioural claims:
§19 Module Chroot Handling and §22 Path Resolution. The rest are wire constants
(CF_SYMLINK_TIMES, CF_SYMLINK_ICONV, the DeleteStats symlink counter) that
the note's own protocol-level argument already covers.

Both subsections re-read against target/interop/upstream-src/rsync-3.5.0/.
Every citation in them had drifted:

claimed actually at 3.5.0
clientserver.c:831 = rsync_module() :739; the decision block is :883-895
clientserver.c:845-862 = the /./ split that range is gid handling; the split is :897-908
backup.c:187-221 = link_or_rename :226; called at :316 and :325
backup.c:288-300 = cross-device recreate that range is the safe-symlink guard
delete.c:165-174 = backup-before-delete :228-230

Two claims were also wrong on substance, not just position:

  • The chroot table said the unset-and-no-/./ probe falls back "on EPERM".
    Upstream tests only chroot("/") < 0 and switches to false on any
    failure, logging strerror(errno) for the operator rather than branching on
    it.
  • The backup-before-delete guard was quoted with two terms. Upstream has three:
    make_backups > 0 && !(flags & DEL_FOR_BACKUP) && (backup_dir || !is_backup_file(fbuf)).
    The omitted DEL_FOR_BACKUP term is what stops a deletion issued by the
    backup machinery itself from recursing into another backup.

The retarget note is narrowed to what it actually covers, and gains an explicit
statement that this document has no section on 3.5.0's confinement model at all

  • the resolver, --confine-root, --insecure-links and the new daemon
    directives are owned by docs/design/upstream-3.5.0-path-confinement-model.md,
    so absence from the compatibility table is not evidence of parity. That was the
    reading most likely to mislead once the old blanket caveat came off.

cargo xtask citations passes: 9029 citations across 5072 files, every one
naming a file rsync 3.5.0 has at a line that file has. As that gate prints
itself, it does not check whether a cited line says what the comment claims -
which is exactly the class fixed here, and why the two subsections were read
against the C rather than re-pointed arithmetically.

….5.0

`docs/UPSTREAM_COMPARISON.md` is titled "vs upstream rsync 3.5.0" but declared
itself **Last verified: 2026-07-22 (against 3.4.4)**, warning that every section
"touching path resolution, symlink handling, chroot or daemon access control"
still described 3.4.4 with 3.4.4 line offsets.

That warning was broader than the document's contents. Grepping those four
topics returns 13 lines, and only two subsections make behavioural claims:
§19 Module Chroot Handling and §22 Path Resolution. The rest are wire constants
(`CF_SYMLINK_TIMES`, `CF_SYMLINK_ICONV`, the `DeleteStats` symlink counter) that
the note's own protocol-level argument already covers.

Both subsections re-read against `target/interop/upstream-src/rsync-3.5.0/`.
Every citation in them had drifted:

| claimed | actually at 3.5.0 |
|---|---|
| `clientserver.c:831` = `rsync_module()` | `:739`; the decision block is `:883-895` |
| `clientserver.c:845-862` = the `/./` split | that range is gid handling; the split is `:897-908` |
| `backup.c:187-221` = `link_or_rename` | `:226`; called at `:316` and `:325` |
| `backup.c:288-300` = cross-device recreate | that range is the safe-symlink guard |
| `delete.c:165-174` = backup-before-delete | `:228-230` |

Two claims were also wrong on substance, not just position:

- The chroot table said the unset-and-no-`/./` probe falls back "on `EPERM`".
  Upstream tests only `chroot("/") < 0` and switches to false on **any**
  failure, logging `strerror(errno)` for the operator rather than branching on
  it.
- The backup-before-delete guard was quoted with two terms. Upstream has three:
  `make_backups > 0 && !(flags & DEL_FOR_BACKUP) && (backup_dir || !is_backup_file(fbuf))`.
  The omitted `DEL_FOR_BACKUP` term is what stops a deletion issued by the
  backup machinery itself from recursing into another backup.

The retarget note is narrowed to what it actually covers, and gains an explicit
statement that this document has no section on 3.5.0's confinement model at all
- the resolver, `--confine-root`, `--insecure-links` and the new daemon
directives are owned by `docs/design/upstream-3.5.0-path-confinement-model.md`,
so absence from the compatibility table is not evidence of parity. That was the
reading most likely to mislead once the old blanket caveat came off.

`cargo xtask citations` passes: 9029 citations across 5072 files, every one
naming a file rsync 3.5.0 has at a line that file has. As that gate prints
itself, it does not check whether a cited line *says* what the comment claims -
which is exactly the class fixed here, and why the two subsections were read
against the C rather than re-pointed arithmetically.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 4, 2026
@oferchen
oferchen merged commit f189931 into master Sep 4, 2026
63 checks passed
@oferchen
oferchen deleted the docs/comparison-350-behavioural-verify branch September 4, 2026 06:35
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