Repository navigation
[W5.9] cli: the transport-interop harness (gate) #24
Description
Unit W5.9 of docs/PLAN.md.
The transport-interop harness in test-plan shape. The gate: the go-libp2p matrix over tcp + /noise + yamux, dial and listen both ways, plus the silent-peer and slow-reader scenarios.
Where the spec lives
- The unit row: root
docs/PLAN.md— the deliverable, the dependencies, the priority. - The frozen interfaces: root
docs/ARCHITECTURE.md, §3 (the mechanisms) and §7, row 11 (this package). - The package's own docs:
packages/cli/docs/ARCHITECTURE.mdand itsPLAN.md— read them first; they refine the root docs and never contradict them. - The reference: the
spikebranch,Interop.lean,scripts/(ping-interop.sh,interop-matrix.sh) (ARCHITECTURE §7). Read it before you implement. Port its tests, keep the wire bytes; the code shape follows §3, not the spike's internals (§7 preamble, §9).
Your freedom, and its cost
The docs govern, and they are yours to change. Where a better design exists, change it — and change the documents in the same pull request. A contract change starts at the root docs/ARCHITECTURE.md; the package docs follow it in the same change. Code that disagrees with the docs, or package docs that disagree with the root, does not merge.
Definition of done
- The public surface follows ARCHITECTURE §4; the owned contracts hold.
- A green matrix run recorded in the issue, the timing JSON in the test-plan's shape, docker confined to the scripts.
- The carried vector and property tests pass through the
Testssuite. lake build,lake test, andlake test -- +RTS -N1 -RTSare green;scripts/lint-imports.shis green.- No
sorry, no build warnings (CLAUDE.md, "Strict checking"). - First submodule under your leaf? Widen the lib's
globsinlakefile.tomlin the same commit.
Depends on
- [W5.8] cli: the demo and ping binaries #22 (
W5.8) — blocking.
Every issue is claimable from day one; you build ahead of open dependencies against mocks of their frozen interfaces (RULES.md, "Working ahead of the tree").
Ground rules
- Comment
claimto take the issue; an organiser assigns it. One issue at a time. - A pull request within 8 hours of the assignment; drafts count. Link the issue (
Closes #N). Miss the window, lose the claim. - Target the
hackathon26branch. - The license-acceptance line of the PR description stays ticked; commits carry no AI co-author trailers. Two guards fail the PR otherwise.
- Prose register everywhere: CLAUDE.md, "Writing Style".
- A contract question the docs do not settle: ask on this issue before you code past it.
Activity
IvanAnishchuk commentedon Nov 4, 2026
The W4.2 pull request (#47) changes the TCP close discipline of root ARCHITECTURE §4.7, which the
Connectionofnet/streamscarries to every layer above it.closesends a FIN when no write is in flight, and an RST when one is. On v4.34, a write to a peer that stops reading never completes. libuv'sshutdownwaits behind it, and the write request holds the socket and its descriptor. A C shim innet/streamsends such a connection, and the peer gets an RST. A failed write follows the same rule.none, the end-of-stream channel of §3.5. go-libp2p closes every TCP connection with an RST (linger 0,vendor/go-libp2p/p2p/transport/tcp/tcp.go, lines 278 to 281), so a session with a go node ends this way.The
Connectiontype and its fields stay the same. Thenet/streamsARCHITECTURE, "Decisions", records both rules with their sources.IvanAnishchuk commentedon Nov 5, 2026
claim
IvanAnishchuk commentedon Nov 5, 2026
#63 (W5.1) lands
libp2p/identityand touches docs and types this unit builds on. No existing signature changes.Libp2p.IdentityexportsKeyType,PubKey,PrivKey,PeerId, andIdentity.Error. The entry points arePubKey.unmarshal?,PrivKey.unmarshal?,PubKey.marshal,PubKey.verify,PrivKey.sign : ByteArray → ExceptT Error IO ByteArray,PrivKey.toPublic,PeerId.ofPubKey,PeerId.ofBytes?,PeerId.toBytes, andPeerId.ofString?.PeerIdderivesBEq,DecidableEq,Hashable,Ord, andRepr, as root §3.2 asks.ToStringprints the parsed text form. The derived==also compares that form, so code that asks "same peer?" comparesa.hash == b.hash.Multiformats.Multihashnow derivesHashableandOrd, and the generated multiformats enums (HashCode,ContentCodec,Protocol,Multibase.Base) deriveOrd.Multiformats.Multiaddr.validPeerHash;PeerIdcarries its proof.feat(cli): W5.9, the transport-interop harness and the matrix script
IvanAnishchuk commentedon Nov 6, 2026
Interface change from W5.2:
StreamHandler.handlenow takes aStreamContext(the provedremotePeerand the connection'sremoteAddr) before the stream. The reason and the full shape are on #15.A handler value or a core mock in this unit's PR needs the new argument. A handler that needs neither field writes
fun _ s => ….feat(cli): W5.9, the transport-interop harness and the matrix script
IvanAnishchuk commentedon Nov 10, 2026
The W5.9 matrix is green on the real stack, with no mock under the harness (#88, closing #73).
db33675867c01e23695cb3152a8b4816e023584eonIvanAnishchuk:seam-interop-stack, stacked on refactor(host): run the upgrade and stream selection on the real negotiate #86 and test(protocols): run the req/resp sim checks between two real hosts #87..lake/build/bin/interop, SHA-2565fa66d2f85809398ea48e708eba7972d0477d8ee36c3db355c7ffc66375209a8.vendor/go-libp2p, throughscripts/interop-matrix.sh.{"handshakePlusOneRTTMillis":6.845,"pingRTTMilllis":0.222}{"handshakePlusOneRTTMillis":52.695,"pingRTTMilllis":1.140}{"handshakePlusOneRTTMillis":135.398,"pingRTTMilllis":0.88}{"handshakePlusOneRTTMillis":55.356,"pingRTTMilllis":1.385}{"handshakePlusOneRTTMillis":137.437,"pingRTTMilllis":1.084}{"stalledAfterBytes":524224,"pingRTTMillis":13.49}0 failed.
IvanAnishchuk commentedon Nov 10, 2026
This record replaces the one above. #88 now stacks on #89, which moves ping onto the real core, so the harness runs with no bridge over any mock. The matrix is green on that build.
2bdb30a36061a1626b7105fce3282b50b27e612eonIvanAnishchuk:seam-interop-stack, stacked on refactor(host): run the upgrade and stream selection on the real negotiate #86, test(protocols): run the req/resp sim checks between two real hosts #87, and refactor(protocols): run identify and ping on the real core and host #89..lake/build/bin/interop, SHA-256cc33582966bd36c8c2377ea029e0bbf1784da5deb77b827886e7c593fdcaf039.vendor/go-libp2p, throughscripts/interop-matrix.sh.{"handshakePlusOneRTTMillis":6.579,"pingRTTMilllis":0.217}{"handshakePlusOneRTTMillis":49.061,"pingRTTMilllis":0.973}{"handshakePlusOneRTTMillis":138.545,"pingRTTMilllis":0.982}{"handshakePlusOneRTTMillis":52.583,"pingRTTMilllis":2.580}{"handshakePlusOneRTTMillis":136.802,"pingRTTMilllis":0.853}{"stalledAfterBytes":524224,"pingRTTMillis":12.417}0 failed.
IvanAnishchuk commentedon Nov 10, 2026
The record above still holds after a rebase of the stack. The commits under #88 changed only suites and docs: the host and protocols suites now run on the fixed-key Noise value and a test clock (root ARCHITECTURE §3.1). The interop binary is byte-identical, SHA-256
cc33582966bd36c8c2377ea029e0bbf1784da5deb77b827886e7c593fdcaf039. Its commit is now013e7f5onIvanAnishchuk:seam-interop-stack, in place of2bdb30a.