docs: restructure TODO.md with phased task queue
Phase 1 (UEPS tests) → Phase 2 (transport) → Phase 3 (controller) → Phase 4 (dispatcher) → Phase 5 (integration/benchmarks) Known issues and wiki inconsistencies documented. Co-Authored-By: Charon <developers@lethean.io>
This commit is contained in:
Claude
parent
c9ac361f63
commit
6d71da4065
1 changed files with 81 additions and 29 deletions
110
TODO.md
110
TODO.md
|
|
@ -1,38 +1,90 @@
|
|||
# TODO
|
||||
# TODO.md — go-p2p Task Queue
|
||||
|
||||
## High Priority — Test Coverage (currently 42%)
|
||||
|
||||
- [ ] **UEPS packet tests** — Zero tests for wire protocol. Need: builder round-trip, HMAC verification, malformed packet rejection, empty payload, oversized payload, max ThreatScore boundary.
|
||||
- [ ] **Transport tests** — 934 lines untested. Need: WebSocket handshake (accept + reject), SMSG encryption round-trip, connection lifecycle, keepalive timeout, rate limiting, deduplication, protocol version mismatch.
|
||||
- [ ] **Controller tests** — 327 lines untested. Need: request-response correlation, timeout handling, auto-connect, concurrent requests, GetAllStats parallel execution.
|
||||
|
||||
## Medium Priority — Coverage Target 70%+
|
||||
|
||||
- [ ] **Dispatcher implementation** — Currently a commented-out stub. Implement UEPS packet routing with threat circuit breaker (drop ThreatScore > 50000) and intent-based dispatch.
|
||||
- [ ] **Integration test** — Full node-to-node handshake over localhost WebSocket with encrypted message exchange.
|
||||
- [ ] **Benchmarks** — Peer scoring (KD-tree), UEPS marshal/unmarshal, identity key generation, message serialisation.
|
||||
- [ ] **bufpool.go tests** — Buffer reuse verification, large buffer handling.
|
||||
|
||||
## Low Priority
|
||||
|
||||
- [ ] **Logging package tests** — Simple but should have coverage for completeness.
|
||||
- [ ] **Peer discovery** — Currently manual peer registration. Add mDNS or DHT-based discovery.
|
||||
- [ ] **Connection pooling** — Transport creates fresh connections; add pool for controller reuse.
|
||||
- [ ] **Error recovery tests** — Handshake timeouts, protocol version mismatch, allowlist rejection, connection drop/reconnect.
|
||||
Dispatched from core/go orchestration. Pick up tasks in phase order.
|
||||
|
||||
---
|
||||
|
||||
## Linux Homelab Assignment (Virgil, 19 Feb 2026)
|
||||
## Phase 1: UEPS Wire Protocol Tests (CRITICAL — 0% coverage)
|
||||
|
||||
This package is assigned to the Linux homelab agent alongside go-rocm. Linux is the natural platform for socket-level networking work — real network interfaces, iptables for testing, no macOS sandbox restrictions.
|
||||
The UEPS packet builder and reader implement HMAC-SHA256 signed TLV frames. Zero tests exist. This is crypto code — it must be tested.
|
||||
|
||||
### Linux-Specific Tasks
|
||||
- [ ] **PacketBuilder round-trip** — Build packet with known fields, marshal+sign, then ReadAndVerify, assert all header fields match and payload is intact.
|
||||
- [ ] **HMAC verification** — Tamper with payload byte after signing, verify ReadAndVerify returns integrity error. Do same for header tampering.
|
||||
- [ ] **Wrong shared secret** — Sign with key A, verify with key B, expect HMAC mismatch.
|
||||
- [ ] **Empty payload** — Payload=nil or []byte{}, should produce valid signed packet.
|
||||
- [ ] **Max ThreatScore boundary** — ThreatScore=65535 (uint16 max), verify serialisation round-trips correctly.
|
||||
- [ ] **Missing HMAC tag** — Craft packet without 0x06 tag, expect "missing HMAC" error from reader.
|
||||
- [ ] **TLV value too large** — Value >255 bytes, expect writeTLV error.
|
||||
- [ ] **Truncated packet** — Short read / EOF mid-TLV, expect io error.
|
||||
- [ ] **Unknown TLV tag** — Insert unknown tag between header TLVs and HMAC, verify reader skips it but includes in signature check.
|
||||
|
||||
- [ ] **Real network integration tests** — Test WebSocket handshake over actual network interfaces (loopback + LAN). macOS sandbox can interfere with raw socket operations.
|
||||
- [ ] **Concurrent connection stress test** — Spawn 100+ peers on localhost, verify connection pooling, deduplication, and rate limiting under load. Linux handles high fd counts better.
|
||||
- [ ] **Firewall interaction** — Test UEPS packet routing through iptables rules. Verify threat circuit breaker works with real packet drops.
|
||||
## Phase 2: Transport Tests (0 tests, 934 lines)
|
||||
|
||||
### Platform
|
||||
Transport is the encrypted WebSocket layer. Tests need real WebSocket connections via httptest.NewServer.
|
||||
|
||||
- **OS**: Ubuntu 24.04 (linux/amd64)
|
||||
- **Co-located with**: go-rocm (AMD GPU inference), go-rag (Qdrant + Ollama)
|
||||
- [ ] **Test pair setup helper** — Create reusable helper that spins up two identities, registries (open auth), transports on random ports. This helper underpins all transport tests.
|
||||
- [ ] **Full handshake** — Client connects to server, challenge-response completes, shared secret derived, both sides have connection.
|
||||
- [ ] **Handshake rejection: wrong protocol version** — Peer with incompatible version gets rejection message before disconnect.
|
||||
- [ ] **Handshake rejection: allowlist** — Peer not in allowlist gets "not authorized" rejection.
|
||||
- [ ] **Encrypted message round-trip** — Send message from A to B via SMSG encryption, verify decrypt and content match.
|
||||
- [ ] **Message deduplication** — Send message with same ID twice, second is dropped silently.
|
||||
- [ ] **Rate limiting** — Burst >100 messages from one peer, verify messages dropped after token bucket empties.
|
||||
- [ ] **MaxConns enforcement** — Fill MaxConns, next connection gets 503 rejection.
|
||||
- [ ] **Keepalive timeout** — No activity beyond PingInterval+PongTimeout, connection cleaned up.
|
||||
- [ ] **Graceful close** — GracefulClose sends disconnect message (MsgDisconnect) before closing.
|
||||
- [ ] **Concurrent sends** — Multiple goroutines sending on same connection, no races (writeMu protects).
|
||||
|
||||
## Phase 3: Controller Tests (0 tests, 327 lines)
|
||||
|
||||
Controller wraps transport for request-response patterns. Test over a real transport pair from Phase 2.
|
||||
|
||||
- [ ] **Request-response correlation** — Send request, worker replies with ReplyTo set, controller matches correctly.
|
||||
- [ ] **Request timeout** — No response within deadline, returns timeout error.
|
||||
- [ ] **Auto-connect** — Peer not connected, controller auto-connects via transport before sending.
|
||||
- [ ] **GetAllStats** — Multiple connected peers, verify parallel stat collection completes.
|
||||
- [ ] **PingPeer RTT** — Send ping, receive pong, RTT calculated and peer metrics updated.
|
||||
- [ ] **Concurrent requests** — Multiple requests in flight to different peers, correct correlation.
|
||||
- [ ] **Dead peer cleanup** — Response channel cleaned up after timeout (no goroutine/memory leak).
|
||||
|
||||
## Phase 4: Dispatcher Implementation
|
||||
|
||||
Currently a commented-out stub in `node/dispatcher.go`. Implement once Phases 1-3 are solid.
|
||||
|
||||
- [ ] **Uncomment and implement DispatchUEPS** — Wire up to Transport for incoming UEPS packets.
|
||||
- [ ] **Threat circuit breaker** — Drop packets with ThreatScore > 50000. Log as threat event.
|
||||
- [ ] **Intent router** — Route by IntentID: 0x01 handshake, 0x20 compute, 0x30 rehab, 0xFF custom.
|
||||
- [ ] **Dispatcher tests** — Unit tests for each intent route and threat rejection.
|
||||
|
||||
## Phase 5: Integration & Benchmarks
|
||||
|
||||
- [ ] **Full integration test** — Two nodes on localhost: identity creation, handshake, encrypted message exchange, UEPS packet routing, graceful shutdown.
|
||||
- [ ] **Benchmarks** — Peer scoring (KD-tree), UEPS marshal/unmarshal, identity key generation, message serialisation, SMSG encrypt/decrypt.
|
||||
- [ ] **bufpool.go tests** — Buffer reuse verification, concurrent access.
|
||||
|
||||
---
|
||||
|
||||
## Known Issues
|
||||
|
||||
1. **UEPS 0xFF payload has no length prefix** — Relies on external TCP framing (io.ReadAll reads to EOF). Not self-delimiting.
|
||||
2. **Potential race in controller.go** — `transport.OnMessage(c.handleResponse)` called during init; message arriving before pending map is ready could theoretically panic.
|
||||
3. **Resource cleanup gaps** — transport.handleWSUpgrade doesn't clean up on handshake timeout; transport.Connect doesn't clean up temp connection on error.
|
||||
4. **Threat score semantics undefined** — Referenced in dispatcher stub and UEPS header but no scoring/routing logic exists.
|
||||
|
||||
## Wiki Inconsistencies Found (Charon, 19 Feb 2026)
|
||||
|
||||
Fixed in wiki update:
|
||||
- ~~Node-Identity page says PublicKey is "hex-encoded"~~ — Code says base64 (identity.go:63)
|
||||
- ~~Protocol-Messages page uses `Sender` field~~ — Code uses `From`/`To` (message.go:66-67)
|
||||
- ~~Peer-Discovery page says Score is 0.0–1.0~~ — Code uses float64 range 0-100 (peer.go:31)
|
||||
|
||||
## Platform
|
||||
|
||||
- **OS**: Ubuntu (linux/amd64) — snider-linux
|
||||
- **Co-located with**: go-rocm, go-rag
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Charon dispatches tasks here after review
|
||||
2. Pick up tasks in phase order
|
||||
3. Mark `[x]` when done, note commit hash
|
||||
4. New discoveries → add notes, flag in FINDINGS.md
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue