go-p2p/docs/history.md

Project History — go-p2p

Phases

Phase 1 — UEPS Wire Protocol Tests

Commit 2bc53ba. Coverage: ueps/ 88.5%.

Implemented the complete test suite for the UEPS binary framing layer. Tests covered every aspect of the TLV encoding and HMAC-SHA256 signing:

• PacketBuilder round-trip: basic, binary payload, elevated threat score, large payload
• HMAC verification: payload tampering detected, header tampering detected, wrong shared secret detected
• Boundary conditions: nil payload, empty slice payload, uint16 max ThreatScore (65,535), TLV value exceeding 255 bytes (writeTLV error path)
• Stream robustness: truncated packets detected at multiple cut points (EOF mid-tag, mid-length, mid-value), missing HMAC tag, unknown TLV tags skipped and included in signed data

The 11.5% gap from 100% coverage is the reader's io.ReadAll error path, which requires a contrived broken io.Reader to exercise.

Phase 2 — Transport Tests

Commit 3ee5553. Coverage: node/ 42% to 63.5%.

Implemented transport layer tests with real WebSocket connections (no mocks). A reusable setupTestTransportPair helper creates two live transports on ephemeral ports and performs identity generation.

Tests covered:

• Full handshake: challenge-response completes, 32-byte shared secret derived
• Handshake rejection: incompatible protocol version (rejection message sent before disconnect)
• Handshake rejection: allowlist mode, peer not authorised
• Encrypted message round-trip: SMSG encrypt on one side, decrypt on other
• Message deduplication: duplicate UUID dropped silently
• Rate limiting: burst of more than 100 messages, subsequent drops after token bucket empties
• MaxConns enforcement: 503 HTTP rejection when limit is reached
• Keepalive timeout: connection cleaned up after PingInterval + PongTimeout elapses
• Graceful close: MsgDisconnect sent before underlying WebSocket close
• Concurrent sends: no data races under go test -race (writeMu protects all writes)

Phase 3 — Controller Tests

Commit 33eda7b. Coverage: node/ 63.5% to 72.1%. 14 test functions.

Also fixed bug P2P-RACE-1 (see Known Issues).

Tests covered:

• Request-response correlation: message sent, worker replies with ReplyTo set, controller matches by ID
• Request timeout: no response within deadline, sendRequest returns timeout error, pending channel cleaned up
• Auto-connect: peer not yet connected, controller calls transport.Connect transparently
• GetAllStats: multiple connected peers, parallel stat collection, all results collected
• PingPeer RTT: ping sent, pong received, RTT calculated in milliseconds, peer metrics updated in registry
• Concurrent requests: multiple in-flight requests to different peers, correct correlation under load
• Dead peer cleanup: response channel closed and removed from pending map after timeout (no goroutine leak)

Phase 4 — Dispatcher Implementation

Commit a60dfdf. Coverage: dispatcher.go 100%.

Replaced the dispatcher stub with a complete implementation. 10 test functions, 17 subtests.

Design decisions recorded at the time:

1. IntentHandler as a func type rather than an interface, matching the MessageHandler pattern already used in transport.go. Lighter weight for a single-method contract.
2. Sentinel errors (ErrThreatScoreExceeded, ErrUnknownIntent, ErrNilPacket) rather than silent drops. Callers can inspect outcomes; the dispatcher still logs at WARN level regardless.
3. Threat check occurs before intent routing. A high-threat packet with an unknown intent returns ErrThreatScoreExceeded, not ErrUnknownIntent. The circuit breaker is the first line of defence.
4. Threshold fixed at 50,000 (a constant, not configurable) to match the original stub specification. The value sits at approximately 76% of uint16 max.
5. sync.RWMutex for the handler map. Registration is infrequent (write lock); dispatch is read-heavy (read lock).

Tests covered: register/dispatch, threat boundary conditions (at threshold, above threshold, uint16 max, zero), unknown intent, multi-handler routing, nil packet, empty payload, concurrent dispatch (50 goroutines), concurrent register-and-dispatch, handler replacement, threat-before-routing ordering, intent constant value verification.

Phase 5 — Integration Tests and Benchmarks

Coverage: race-free under go test -race.

Three integration tests (TestIntegration_*) exercise the full stack end-to-end:

• TestIntegration_TwoNodeHandshakeAndMessage: two nodes on localhost, identity creation, handshake, encrypted message exchange, controller ping/pong with RTT measurement, UEPS packet routing via dispatcher, threat circuit breaker verification, graceful shutdown with disconnect message.
• TestIntegration_SharedSecretAgreement: verifies that two independently created nodes derive identical 32-byte shared secrets via X25519 ECDH (fundamental correctness property).
• TestIntegration_GetRemoteStats_EndToEnd: full stats retrieval across a real WebSocket connection with worker and controller wired together.

13 benchmark functions across node/ and ueps/:

• Identity operations: keygen, shared secret derivation, challenge generation, challenge sign+verify
• Message operations: serialise
• Transport operations: SMSG encrypt+decrypt
• Peer registry: KD-tree select, KD-tree rebuild
• UEPS: marshal, read+verify
• Buffer pool: get/put (zero allocations confirmed)

9 buffer pool tests (bufpool_test.go): get/put round-trip, buffer reuse verification, large buffer eviction (buffers exceeding 64 KB are not returned to the pool), concurrent get/put (100 goroutines × 50 iterations), buffer independence, MarshalJSON correctness for 7 payload types, independent copy verification, HTML escaping disabled, concurrent MarshalJSON.

Known Limitations

UEPS 0xFF Payload Not Self-Delimiting

The TagPayload (0xFF) field carries no length prefix. ReadAndVerify calls io.ReadAll on the remaining stream, which means the packet format relies on external TCP framing to delimit the packet boundary. The enclosing transport must provide a length-prefixed frame before calling ReadAndVerify. This is noted in comments in both packet.go and reader.go but no solution is implemented.

Consequence: UEPS packets cannot be chained in a raw stream without an outer framing protocol. The current WebSocket transport encapsulates each UEPS frame in a single WebSocket message, which provides the necessary boundary implicitly.

No Resource Cleanup on Some Error Paths

transport.handleWSUpgrade does not clean up on handshake timeout (the pendingConns counter is decremented correctly via defer, but the underlying WebSocket connection may linger briefly before the read deadline fires). transport.Connect does not clean up the temporary connection object on handshake failure (the raw WebSocket conn is closed, but there is no registry or metrics cleanup for the partially constructed PeerConnection).

These are low-severity gaps. They do not cause goroutine leaks under the current implementation because the connection's read loop is not started until after a successful handshake.

Controller Race (Resolved)

The originally identified risk — that transport.OnMessage(c.handleResponse) is called during NewController initialisation and a message arriving before the pending map is ready could cause a panic — was confirmed to be a false alarm. The pending map is initialised in NewController before OnMessage is called, and handleResponse uses a mutex on all map access. No panic is possible.

Bugs Fixed

P2P-RACE-1 — GracefulClose Data Race (Phase 3)

GracefulClose previously called pc.Conn.SetWriteDeadline() outside of writeMu, racing with concurrent Send() calls that also set the write deadline. Detected by go test -race.

Fix: removed the bare SetWriteDeadline call from GracefulClose. The method now relies entirely on Send(), which manages write deadlines under writeMu. This is documented in a comment in transport.go to prevent the pattern from being reintroduced.

Wiki Corrections (19 February 2026)

Three wiki inconsistencies were identified and corrected:

• The Node-Identity page stated PublicKey is hex-encoded. The code uses base64 (identity.go:63).
• The Protocol-Messages page used a Sender field. The code uses From and To (message.go:66-67).
• The Peer-Discovery page stated Score is in the range 0.0–1.0. The code uses a float64 range of 0–100 (peer.go:31).