docs: add CLAUDE.md project instructions
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider
parent
e24df2c9fa
commit
39049106c1
1 changed files with 59 additions and 6 deletions
65
CLAUDE.md
65
CLAUDE.md
|
|
@ -1,22 +1,54 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project
|
||||
|
||||
`go-p2p` is the P2P networking layer for the Lethean network. Module path: `forge.lthn.ai/core/go-p2p`
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Private dependencies (`Borg`, `Poindexter`, `Enchantrix`) are hosted on `forge.lthn.ai`. Required env:
|
||||
```bash
|
||||
GOPRIVATE=forge.lthn.ai
|
||||
```
|
||||
SSH key must be configured for `git@forge.lthn.ai:2223`. Push to `forge` remote only.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
go test ./... # Run all tests
|
||||
go test -run TestName ./... # Single test
|
||||
go test -race ./... # Race detector (required before any PR)
|
||||
go test -short ./... # Skip integration tests
|
||||
go test -cover ./node # Coverage for node package
|
||||
go test -bench . ./... # Benchmarks
|
||||
go test -short ./... # Skip integration tests (they bind real TCP ports)
|
||||
go test -cover ./node # Coverage for a specific package
|
||||
go test -bench . -benchmem ./... # Benchmarks with allocation tracking
|
||||
go vet ./... # Static analysis
|
||||
golangci-lint run ./... # Linting
|
||||
```
|
||||
|
||||
## Key Interfaces
|
||||
## Architecture
|
||||
|
||||
Three packages plus one subpackage:
|
||||
|
||||
```
|
||||
node/ — P2P mesh: identity, transport, peers, protocol, workers, controller, dispatcher, bundles
|
||||
node/levin/ — CryptoNote Levin binary protocol (standalone, no parent imports)
|
||||
ueps/ — UEPS wire protocol (RFC-021): TLV packet builder and stream reader (stdlib only)
|
||||
logging/ — Structured levelled logger with component scoping (stdlib only)
|
||||
```
|
||||
|
||||
### Data flow
|
||||
|
||||
1. **Identity** (`identity.go`) — Ed25519 keypair via Borg STMF. Shared secrets derived via X25519 ECDH + SHA-256.
|
||||
2. **Transport** (`transport.go`) — WebSocket server/client (gorilla/websocket). Handshake exchanges `NodeIdentity` + HMAC-SHA256 challenge-response. Post-handshake messages are Borg SMSG-encrypted. Includes deduplication (5-min TTL), rate limiting (token bucket: 100 burst/50 per sec), and MaxConns enforcement.
|
||||
3. **Dispatcher** (`dispatcher.go`) — Routes verified UEPS packets to intent handlers. Threat circuit breaker drops packets with `ThreatScore > 50,000` before routing.
|
||||
4. **Controller** (`controller.go`) — Issues requests to remote peers using a pending-map pattern (`map[string]chan *Message`). Auto-connects to peers on demand.
|
||||
5. **Worker** (`worker.go`) — Handles incoming commands via `MinerManager` and `ProfileManager` interfaces.
|
||||
6. **Peer Registry** (`peer.go`) — KD-tree peer selection across 4 dimensions (latency, hops, geography, reliability). Persistence uses atomic rename with 5-second debounced writes.
|
||||
7. **Levin** (`node/levin/`) — CryptoNote binary protocol: header parsing, portable storage decode, varint encoding. Completely standalone subpackage.
|
||||
|
||||
### Key interfaces
|
||||
|
||||
```go
|
||||
// MinerManager — decoupled miner control (worker.go)
|
||||
|
|
@ -33,14 +65,32 @@ type ProfileManager interface {
|
|||
}
|
||||
```
|
||||
|
||||
### Dependency codenames
|
||||
|
||||
- **Borg** — STMF crypto (key generation), SMSG (symmetric encryption), TIM (deployment bundle encryption)
|
||||
- **Poindexter** — KD-tree for peer selection
|
||||
- **Enchantrix** — Secure environment (indirect, via Borg)
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- UK English (colour, organisation, centre)
|
||||
- UK English (colour, organisation, centre, behaviour, recognise)
|
||||
- All parameters and return types explicitly annotated
|
||||
- Tests use `testify` assert/require; table-driven subtests with `t.Run()`
|
||||
- Licence: EUPL-1.2
|
||||
- Test name suffixes: `_Good` (happy path), `_Bad` (expected errors), `_Ugly` (panic/edge cases)
|
||||
- Licence: EUPL-1.2 — new files need `// SPDX-License-Identifier: EUPL-1.2`
|
||||
- Security-first: do not weaken HMAC, challenge-response, Zip Slip defence, or rate limiting
|
||||
- Use `logging` package only — no `fmt.Println` or `log.Printf` in library code
|
||||
- Hot-path debug logging uses sampling pattern: `if counter.Add(1)%interval == 0`
|
||||
|
||||
### Transport test helper
|
||||
|
||||
Tests needing live WebSocket endpoints use the reusable helper:
|
||||
```go
|
||||
tp := setupTestTransportPair(t) // creates two transports on ephemeral ports
|
||||
pc := tp.connectClient(t) // performs real handshake, returns *PeerConnection
|
||||
// tp.Server, tp.Client, tp.ServerNode, tp.ClientNode, tp.ServerReg, tp.ClientReg
|
||||
```
|
||||
Cleanup is automatic via `t.Cleanup`.
|
||||
|
||||
## Commit Format
|
||||
|
||||
|
|
@ -50,6 +100,9 @@ type(scope): description
|
|||
Co-Authored-By: Virgil <virgil@lethean.io>
|
||||
```
|
||||
|
||||
Types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`, `perf`, `ci`
|
||||
Scopes: `node`, `ueps`, `logging`, `transport`, `peer`, `dispatcher`, `identity`, `bundle`, `controller`, `levin`
|
||||
|
||||
## Documentation
|
||||
|
||||
- `docs/architecture.md` — full package and component reference
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue