Skip to content

refactor(client): split the peer session into cohesive modules - #118

Merged
DontBlameMeDev merged 3 commits into
mainfrom
refactor/peer-split
Oct 19, 2026
Merged

DontBlameMeDev merged 3 commits into
mainfrom
refactor/peer-split

Conversation

@DontBlameMeDev

Copy link
Copy Markdown
Member

crates/client/src/peer.rs was 5633 lines — about half the client crate — of which 2180 are
the state machine and 3453 its tests. It is now a directory: mod.rs keeps the PeerSession
struct and the module wiring, and one concern lives per file. Nothing is broken and no
fail-first test exists or was invented; this is a move, verified as one below.

Module map

file lines what it holds
mod.rs 149 the module doc, the wiring (mod, pub use, the shared imports), and the PeerSession struct with its fields
invite.rs 205 PROTOCOL.md §5.1's invite: the link, its two keys, the connection address, and PeerInvite's redacting Debug
options.rs 123 PeerOptions, FRAME_BUDGET, and the host producer half built from them (§7.1)
report.rs 103 Outcome, Published, Counted, Applied, Dropped, Ending — §13.11's decisions and the four endings
plaintext.rs 60 the y-protocols side of a kind = 0 frame: the session document, one message's bytes, and whether a plaintext is content or a handshake
clocks.rs 144 the caller's tick: §13.7's lease, §8.2's awareness expiry, §13.8's host-away window, §13.3's no-state window, §13.11's mutation census
roles.rs 116 §13.4's attribution read back, and the eligibility §13.6's reciprocal and readiness accounting turns on
deliver.rs 378 one frame in: CANONICAL.md §6.1's verdict, §13's decision, and the y-protocols messages a content frame carries
publish.rs 289 everything that leaves: the seal, §13.6's publication gates, the announcement and its renewal, the handshake, and the two ways a host's publishing ends
holds.rs 128 §13.7: the paths this client offers, the lease a peer's holds live under, and the expiry that forgets them
events.rs 67 what a driver hands in that is not a frame: peer.joined, peer.left, and a host's listing changing under it
read.rs 353 what a caller reads off a session: its keys, its roles, its counts, its replica and its outgoing frames
speculation.rs 238 §13.9: the local edits a session may not publish yet, the clean baseline they are held apart from, and what a resolved role does with them
tests.rs 3407 the unit tests, beside the modules they cover

5760 lines in total against the original 5633: the 127 are the thirteen module headers, their
use lines and the mod declarations in mod.rs.

Each module's doc comment is the paragraph above, so the map reads from the files as well as
from here.

Verified as a pure move

The work is three commits, each a move on its own:

  1. peer.rs becomes peer/mod.rs with no content change — git show --stat -M reports
    rename crates/client/src/{peer.rs => peer/mod.rs} (100%).
  2. The modules are extracted; mod.rs keeps the struct, the wiring, and the tests still inline.
  3. The inline mod tests becomes peer/tests.rs.

The extraction was then compared against origin/main's peer.rs mechanically, with attributes,
use trees and /// blocks compared as well as code (an editorial move is verified by what it
carries, not by a green suite):

code tokens: original=32704 extraction=32704
  (before folding rustfmt's vertical trailing commas: lost=0, gained=2)
  only in original: 0 (0 distinct)
  only in extraction: 0 (0 distinct)
attributes: original=138 extraction=138
  only in original: 0
  only in extraction: 0
use names: original=76 extraction=98
  imported names only in original: 0
doc lines: original=603 extraction=603
  only in original: 0
  only in extraction: 0

VERDICT: pure move

What it does: tokenise both sides; drop comments, use and mod declarations, #[..] attributes
and pub qualifiers; unwrap each impl PeerSession { .. } wrapper on both sides, since one of
those per module is the extraction itself; compare the resulting multisets. Separately compare the
#[..] attribute multiset, the set of names the use trees import (each module now imports its
own use super::.. header, so the counts cannot match and only a lost name can), and the ///
line multiset. It is 291 lines of Python, reading git show <rev>:crates/client/src/peer.rs and the working
tree; it is below so a reviewer can re-run it: see the fold-out.

Two differences are expected and are why the numbers are folded rather than equal:

  • +2 commas. Widening a signature with the pub(super) it needs pushes it past the 80-column
    width, so rustfmt lays the parameter list out vertically and a trailing comma appears that the
    one-line form did not have. Four signatures break this way (host_producer, publish_state,
    renew_lease, publish); one comma disappears in tests.rs where removing the mod tests {
    wrapper shortens a line enough to join it.
  • +1 #[cfg(test)] moves from the inline mod tests to the declaration of the out-of-line one.
    It is excluded from both sides.

Two items a draft of this extraction had dropped are restored, and the check above is what caught
them: impl fmt::Debug for PeerInvite, which is what keeps §5.1's two keys out of a log, and the
PeerSession doc line. Both are in the doc lines and code tokens counts above.

No visibility beyond the extraction: a moved item is pub(super) where a sibling module calls it,
and private where it already was. No item moved from pub to anything narrower, so the crate's
public surface (PeerSession, PeerInvite, PeerOptions, FRAME_BUDGET, wire_address,
Outcome, Published, Applied, Dropped, Ending, re-exported from crate::peer) is
unchanged.

Gate

nix build .#checks.x86_64-linux.{fmt,clippy,nextest}, before and after.

Before — origin/main (5a83020) in a worktree:

selvaged-fmt>     +++ command cargo fmt -- --check
selvaged-clippy>  +++ command cargo clippy --release --locked --workspace --all-features --all-targets -- -D warnings
selvaged-clippy>      Finished `release` profile [optimized] target(s) in 2.73s
selvaged-nextest>     Starting 234 tests across 17 binaries
selvaged-nextest>      Summary [  17.316s] 234 tests run: 234 passed, 0 skipped

After — this branch, EXIT=0 for both invocations:

selvaged-fmt>     +++ command cargo fmt -- --check
selvaged-clippy>  +++ command cargo clippy --release --locked --workspace --all-features --all-targets -- -D warnings
selvaged-clippy>      Finished `release` profile [optimized] target(s) in 1.33s
selvaged-nextest>     Starting 234 tests across 17 binaries
selvaged-nextest>      Summary [  17.204s] 234 tests run: 234 passed, 0 skipped

The test inventory is asserted independently of the runner: the tree carries 190 #[test] items
before and after, 84 of them in peer.

Reviewer risks

  • The diff is a move, so read the module map, not the lines. The only lines that are not a
    move are the thirteen module headers in mod.rs's wiring, the pub(super) on items a sibling
    calls, and the fifteen lines of tests.rs's import block.
  • tests.rs is 3407 lines and still the largest file in the crate. It is one mod tests, left
    whole on purpose: splitting tests between modules is a different change with a different review.
    The two visibility neighbours (MAX_REPLIES_PER_FRAME in deliver, ReadState) are still
    private to their modules because nothing outside them reads them.
  • mod.rs is 149 lines of struct fields. The struct is where it was; only the impl blocks
    moved out. A follow-up could group the fields, but that is a different change.
  • Commits 2 and 3 are each a pure move but only their end state was built; commit 1 is
    byte-identical to main by construction.
The check, in full
#!/usr/bin/env python3
"""Prove that crates/client/src/peer/ is a pure move of the old crates/client/src/peer.rs.

Two independent checks:

  1. code tokens (identifiers, literals, punctuation; comments, attributes, `use` and
     `mod` declarations removed) are compared as multisets.  The only structural
     difference an extraction introduces is one `impl PeerSession { ... }` wrapper per
     module that carries one, so those wrappers are unwrapped before comparing.
  2. `use`-tree leaf paths, `#[..]` attribute lines and `///` doc lines are compared,
     so a dropped import, attribute or doc block is reported.
"""

import collections
import re
import subprocess
import sys

REPO = "/home/user/projects/selvage-fix/rs-peer-split/reference_server"
BASE = "5a83020"  # origin/main at the time of the split; peer.rs is identical at dd61b5e

TOKEN = re.compile(
    r"""(?P<comment>//[^\n]*)
      | (?P<string>r?"(?:[^"\\]|\\.)*")
      | (?P<char>'(?:[^'\\]|\\.)')
      | (?P<ident>[A-Za-z_][A-Za-z0-9_]*)
      | (?P<num>\d[\d_]*(?:\.\d+)?(?:[A-Za-z_]\w*)?)
      | (?P<punct>[^\sA-Za-z0-9_])""",
    re.X,
)


def raw_tokens(text):
    out = []
    for m in TOKEN.finditer(text):
        kind = m.lastgroup
        if kind == "comment":
            if m.group().startswith("///"):
                out.append(("doc", m.group()[3:].strip()))
            continue
        out.append((kind, m.group()))
    return out


def code_tokens(toks):
    """Drop docs, attributes, `use` and `mod` declarations, and `pub` qualifiers."""
    out = []
    i = 0
    while i < len(toks):
        kind, val = toks[i]
        if kind == "doc":
            i += 1
            continue
        if kind == "punct" and val == "#":
            j = i + 1
            if j < len(toks) and toks[j] == ("punct", "!"):
                j += 1
            if j < len(toks) and toks[j] == ("punct", "["):
                depth = 0
                while j < len(toks):
                    if toks[j] == ("punct", "["):
                        depth += 1
                    elif toks[j] == ("punct", "]"):
                        depth -= 1
                        if depth == 0:
                            break
                    j += 1
                i = j + 1
                continue
        if kind == "ident" and val == "use":
            j = i
            depth = 0
            while j < len(toks):
                if toks[j] == ("punct", "{"):
                    depth += 1
                elif toks[j] == ("punct", "}"):
                    depth -= 1
                elif toks[j] == ("punct", ";") and depth == 0:
                    break
                j += 1
            i = j + 1
            continue
        if kind == "ident" and val == "mod":
            j = i + 1
            if j < len(toks) and toks[j] == ("punct", "("):
                while j < len(toks) and toks[j] != ("punct", ")"):
                    j += 1
                j += 1
            while j < len(toks) and toks[j][0] == "ident":
                j += 1
            if j < len(toks) and toks[j] == ("punct", ";"):
                i = j + 1
                continue
        if kind == "ident" and val == "pub":
            j = i + 1
            if j < len(toks) and toks[j] == ("punct", "("):
                depth = 0
                while j < len(toks):
                    if toks[j] == ("punct", "("):
                        depth += 1
                    elif toks[j] == ("punct", ")"):
                        depth -= 1
                        if depth == 0:
                            break
                    j += 1
                i = j + 1
                continue
            i += 1
            continue
        out.append((kind, val))
        i += 1
    return out


def unwrap_inherent_session_impls(toks):
    """Delete each `impl PeerSession {` and its matching `}`, keeping the body."""
    drop = set()
    i = 0
    while i + 2 < len(toks):
        if (
            toks[i] == ("ident", "impl")
            and toks[i + 1] == ("ident", "PeerSession")
            and toks[i + 2] == ("punct", "{")
        ):
            depth = 0
            j = i + 2
            while j < len(toks):
                if toks[j] == ("punct", "{"):
                    depth += 1
                elif toks[j] == ("punct", "}"):
                    depth -= 1
                    if depth == 0:
                        break
                j += 1
            drop.update((i, i + 1, i + 2, j))
            i = j + 1
            continue
        i += 1
    return [t for n, t in enumerate(toks) if n not in drop]


def drop_trailing_commas(toks):
    """Remove `,` directly before `)`/`}`/`]`/`>`.

    Moving an item into a module can widen its signature by the `pub(super) ` it
    needs, which pushes it over the line width and makes rustfmt lay the parameter
    list out vertically -- and a vertical list carries a trailing comma the one-line
    form did not. Those commas are the layout's, not the code's, so both sides are
    folded the same way; the unfolded delta is reported beside this one.
    """
    out = []
    for i, tok in enumerate(toks):
        if tok == ("punct", ",") and i + 1 < len(toks):
            nxt = toks[i + 1]
            if nxt in (("punct", ")"), ("punct", "}"), ("punct", "]"), ("punct", ">")):
                continue
        out.append(tok)
    return out


def use_paths(text):
    """Every `use`-tree leaf identifier, so a dropped import shows up by name."""
    leaves = []
    for m in re.finditer(r"(?m)^\s*(?:pub(?:\([^)]*\))?\s+)?use\b([^;]*);", text):
        tree = m.group(1)
        for part in re.split(r"[,{}]", tree):
            part = part.strip()
            if part:
                leaves.append(part)
    return leaves


def attributes(text):
    out = []
    for m in re.finditer(r"(?m)^\s*#\[", text):
        depth = 0
        i = m.start() + 1
        while i < len(text):
            if text[i] == "[":
                depth += 1
            elif text[i] == "]":
                depth -= 1
                if depth == 0:
                    break
            i += 1
        out.append(re.sub(r"\s+", " ", text[m.start() : i + 1]).strip())
    return out


def main():
    original = subprocess.run(
        ["git", "-C", REPO, "show", BASE + ":crates/client/src/peer.rs"],
        check=True,
        capture_output=True,
        text=True,
    ).stdout
    lines = original.split("\n")
    wrapper = next(i for i, l in enumerate(lines) if l.strip() == "mod tests {")
    # the pre-test half, without its trailing `#[cfg(test)]`
    head = lines[:wrapper]
    while head and head[-1].strip() in ("", "#[cfg(test)]"):
        head.pop()
    body = lines[wrapper + 1 :]
    while body and body[-1].strip() == "":
        body.pop()
    assert body[-1].strip() == "}", body[-1]
    body = body[:-1]
    dedented = [l[4:] if l.startswith("    ") else l for l in body]
    old = "\n".join(head + dedented)

    import glob

    new = "\n".join(open(f).read() for f in sorted(glob.glob(REPO + "/crates/client/src/peer/*.rs")))

    old_code = unwrap_inherent_session_impls(code_tokens(raw_tokens(old)))
    new_code = unwrap_inherent_session_impls(code_tokens(raw_tokens(new)))
    raw_lost = collections.Counter(x for x in old_code if x[0] != "doc") - collections.Counter(
        x for x in new_code if x[0] != "doc"
    )
    raw_gained = collections.Counter(x for x in new_code if x[0] != "doc") - collections.Counter(
        x for x in old_code if x[0] != "doc"
    )
    old_code = drop_trailing_commas(old_code)
    new_code = drop_trailing_commas(new_code)
    folded = collections.Counter(x for x in old_code if x[0] != "doc")
    newd = collections.Counter(x for x in new_code if x[0] != "doc")
    lost = folded - newd
    gained = newd - folded

    print(f"code tokens: original={len(old_code)} extraction={len(new_code)}")
    print(
        f"  (before folding rustfmt's vertical trailing commas: "
        f"lost={sum(raw_lost.values())}, gained={sum(raw_gained.values())})"
    )
    print(f"  only in original: {sum(lost.values())} ({len(lost)} distinct)")
    for tok, n in lost.most_common(20):
        print(f"    -x{n} {tok[0]} {tok[1]!r}")
    print(f"  only in extraction: {sum(gained.values())} ({len(gained)} distinct)")
    for tok, n in gained.most_common(20):
        print(f"    +x{n} {tok[0]} {tok[1]!r}")

    # the out-of-line test module is declared with `#[cfg(test)]`, which the inline one
    # carried on `mod tests` itself; neither side is asked to account for it.
    old_attrs = collections.Counter(a for a in attributes(old) if a != "#[cfg(test)]")
    new_attrs = collections.Counter(a for a in attributes(new) if a != "#[cfg(test)]")
    attr_lost = old_attrs - new_attrs
    attr_gained = new_attrs - old_attrs
    print(f"attributes: original={sum(old_attrs.values())} extraction={sum(new_attrs.values())}")
    print(f"  only in original: {sum(attr_lost.values())}")
    for a, n in attr_lost.most_common(10):
        print(f"    -x{n} {a[:110]}")
    print(f"  only in extraction: {sum(attr_gained.values())}")
    for a, n in attr_gained.most_common(10):
        print(f"    +x{n} {a[:110]}")

    # one `use a::{b, c};` becomes several single-item imports and each module gains its
    # own `use super::..` header, so the counts cannot match: what must match is that every
    # name the original imported is still imported somewhere.
    def use_names(text):
        names = set()
        for m in re.finditer(r"(?m)^\s*(?:pub(?:\([^)]*\))?\s+)?use\b([^;]*);", text):
            names.update(re.findall(r"[A-Za-z_][A-Za-z0-9_]*", m.group(1)))
        names.discard("as")
        names.discard("self")
        return names

    old_uses = use_names(old)
    new_uses = use_names(new)
    print(f"use names: original={len(old_uses)} extraction={len(new_uses)}")
    missing = old_uses - new_uses
    print(f"  imported names only in original: {len(missing)}")
    for p in sorted(missing):
        print(f"    -{p}")

    old_docs = collections.Counter(v for k, v in raw_tokens(old) if k == "doc")
    new_docs = collections.Counter(v for k, v in raw_tokens(new) if k == "doc")
    print(f"doc lines: original={sum(old_docs.values())} extraction={sum(new_docs.values())}")
    print(f"  only in original: {sum((old_docs - new_docs).values())}")
    for d, n in (old_docs - new_docs).most_common(10):
        print(f"    -x{n} {d[:110]}")
    print(f"  only in extraction: {sum((new_docs - old_docs).values())}")
    for d, n in (new_docs - old_docs).most_common(10):
        print(f"    +x{n} {d[:110]}")

    ok = not lost and not gained and not attr_lost and not attr_gained and not missing
    print("\nVERDICT:", "pure move" if ok else "MISMATCH")
    return 0 if ok else 1


if __name__ == "__main__":
    sys.exit(main())

DontBlameMe added 3 commits October 19, 2026 11:45
`crates/client/src/peer.rs` becomes `crates/client/src/peer/mod.rs` with no content change. The split that follows needs somewhere to put its files, and a rename on its own is a diff with nothing to read.
`mod.rs` keeps the `PeerSession` struct and the module wiring; one concern per file
around it:

  invite        §5.1's link, its two keys and the connection address
  options       what a session is opened with, and the host producer half
  report        §13.11's decisions, the two counts and the four endings
  plaintext     the y-protocols side of a `kind = 0` frame
  clocks        the caller's tick: the lease, the two presence windows, the census
  roles         §13.4's attribution and §13.6's eligibility
  deliver       one frame in: the verdict, §13's decision, the messages it carried
  publish       everything that leaves: the seal, the gates, the announcement
  holds         §13.7's paths, the lease and its expiry
  events        what a driver hands in that is not a frame
  read          what a caller reads off a session
  speculation   §13.9's held edits and the clean baseline

Every item moves unchanged: no logic, no signature, and no visibility beyond the
extraction itself.
…over

The inline `mod tests` becomes `peer/tests.rs`, and the imports it was getting from
`use super::*` -- which reached whatever `peer.rs` imported -- are restated from the
modules that now hold them. The tests themselves are unchanged.
Copilot AI balanced review requested due to automatic review settings October 19, 2026 09:50

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@DontBlameMeDev
DontBlameMeDev requested a balanced review from Copilot October 19, 2026 09:50

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@DontBlameMeDev

Copy link
Copy Markdown
Member Author

@coderabbitai review

A note on the review round, so the state is read from here rather than inferred from silence.

CI is green. checks, container, both smoke jobs and publish-rehearsal all pass;
publish and release are skipped, as they are on a pull request. The repository gate was also
run locally, before and after, and is in the body:
nix build .#checks.x86_64-linux.{fmt,clippy,nextest} — 234 tests run: 234 passed, 0 skipped
on both sides, clippy clean under --workspace --all-features --all-targets -- -D warnings.

Copilot could not review. Both of its rounds carry the same message:

Copilot was unable to review this pull request because the user who requested the review has
reached their quota limit.

So there is nothing to answer from it.

CodeRabbit has not posted a round since it was added as a reviewer. This is a large diff that
is a pure move, so the useful read is the module map in the body, the token-level check at the
bottom of it, and git show -M for the rename in the first commit.

The branch is left unmerged for the owner to land.

@DontBlameMeDev
DontBlameMeDev merged commit 09af7dc into main Oct 19, 2026
7 checks passed
@DontBlameMeDev
DontBlameMeDev deleted the refactor/peer-split branch October 19, 2026 10:02
@coderabbitai

coderabbitai Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
⚠️ Action not completed

Pull request is closed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants