Comprehensive testing infrastructure for the Saorsa P2P network ecosystem.

Saorsa Testnet is a centralized workspace for all P2P network testing binaries. It consolidates testing for:

• ant-quic - QUIC transport with NAT traversal
• saorsa-gossip - Gossip protocol and CRDT sync
• saorsa-core - Core P2P library
• saorsa-node - Full network nodes

saorsa-testnet/
├── Cargo.toml                          # Workspace manifest
├── crates/
│   ├── quic-test/                      # QUIC and NAT traversal testing
│   │   ├── src/
│   │   │   ├── main.rs                 # saorsa-quic-test binary
│   │   │   ├── bin/
│   │   │   │   ├── saorsa-testctl.rs   # Test controller
│   │   │   │   └── test-agent.rs       # VPS test agent
│   │   │   ├── harness/                # Test harness framework
│   │   │   ├── registry/               # Peer registry
│   │   │   ├── tui/                    # Terminal UI
│   │   │   └── ...
│   │   └── Cargo.toml
│   ├── gossip-test/                    # Gossip protocol testing (planned)
│   ├── core-test/                      # Core library testing (planned)
│   └── node-test/                      # Full node testing (planned)
├── docs/
│   └── infrastructure/
│       └── VPS_INFRASTRUCTURE.md       # Complete VPS documentation
└── .claude/
    └── skills/
        └── vps-test/                   # Autonomous VPS testing skill
            └── SKILL.md

# Install cargo-zigbuild for cross-compilation
cargo install cargo-zigbuild

# Install zig (macOS)
brew install zig

# Standard build
cargo build --release

# Cross-compile for Linux VPS
cargo zig build --release --target x86_64-unknown-linux-gnu

# Run the main test orchestrator
cargo run -p saorsa-quic-test -- --help

# Run with TUI dashboard
cargo run -p saorsa-quic-test -- --dashboard

# Run test controller
cargo run -p saorsa-quic-test --bin saorsa-testctl -- --help

Every saorsa-quic-test node now boots a Communitas demo identity and MCP server alongside the QUIC tester. This lets you open two TUIs and exchange real Communitas messages/files without any extra setup:

# Terminal 1
cargo run -p saorsa-quic-test -- --data-dir /tmp/node-a

# Terminal 2
cargo run -p saorsa-quic-test -- --data-dir /tmp/node-b

Each node derives a deterministic four-word identity from its peer ID, auto-creates a per-node Communitas vault under <data_dir>/communitas/<four-words>, and exposes bespoke MCP forms in the TUI. To disable the embedded Communitas stack (for very low-memory test rigs) pass --no-communitas.

10 nodes across 3 cloud providers with full NAT simulation:

See docs/infrastructure/VPS_INFRASTRUCTURE.md for complete details including IP addresses, SSH access, and NAT configuration.

NEVER build on VPS machines. All binaries must be:

1. Built locally using cargo zig build
2. Uploaded via SCP

# Build for Linux
cargo zig build --release --target x86_64-unknown-linux-gnu

# Deploy
BINARY="target/x86_64-unknown-linux-gnu/release/saorsa-quic-test"
for n in {2..10}; do
    scp "$BINARY" root@saorsa-$n.saorsalabs.com:/opt/saorsa-test/
    ssh root@saorsa-$n.saorsalabs.com 'systemctl restart saorsa-quic-test'
done

The /vps-test Claude Code skill provides autonomous deployment and testing:

# In Claude Code session
/vps-test start           # Interactive test setup with interview
/vps-test status          # Show all active test loops
/vps-test nodes           # List VPS infrastructure
/vps-test diagnose saorsa-4   # Debug specific node
/vps-test logs ant-quic   # View test logs

Features:

• Mandatory interview process before each test
• Local-only builds with cargo-zigbuild
• Automated fix cycles on failure
• Graduated success verification (1hr, 6hr soak tests)
• Voice notifications via 11Labs

See .claude/skills/vps-test/SKILL.md for complete documentation.

Tests QUIC transport and NAT traversal:

• Connectivity Matrix: All-to-all connection testing
• NAT Traversal: Full Cone, Address Restricted, Port Restricted, Symmetric
• Throughput: Bandwidth measurement across nodes
• Gossip Integration: Message broadcast verification

Tests gossip protocol layer:

• Message broadcast verification
• CRDT state synchronization
• Membership protocol
• Epidemic spread analysis

Tests saorsa-core library:

• Integration test runner
• Property-based tests
• Stress tests

Tests full saorsa-node:

• Health check endpoint
• Sync verification
• Storage tests
• Retrieval tests

# Check compilation
cargo check

# Run tests
cargo test

# Build release
cargo build --release

# Cross-compile for Linux
cargo zig build --release --target x86_64-unknown-linux-gnu

# Lint
cargo clippy --all-targets -- -D warnings

# Format
cargo fmt --all

1. Create new crate:

   mkdir -p crates/my-test/src

2. Add Cargo.toml using workspace dependencies:

   [package]
   name = "saorsa-my-test"
   version.workspace = true
   edition.workspace = true
   
   [dependencies]
   tokio.workspace = true
   anyhow.workspace = true

3. Add to workspace in root Cargo.toml:

   [workspace]
   members = [
       "crates/quic-test",
       "crates/my-test",  # Add here
   ]

The registry at saorsa-1 provides peer discovery:

# List registered peers
curl https://saorsa-1.saorsalabs.com/api/peers

# Health check
curl https://saorsa-1.saorsalabs.com/health

# Dashboard
open https://saorsa-1.saorsalabs.com

Prometheus metrics available at /metrics on each node:

• saorsa_connections_total - Total connection attempts
• saorsa_nat_traversal_success - NAT traversal success rate
• saorsa_gossip_messages_total - Gossip messages sent/received
• saorsa_throughput_bytes - Data transferred

Dashboard: https://saorsa-1.saorsalabs.com

MIT OR Apache-2.0

• ant-quic - QUIC transport with NAT traversal
• saorsa-gossip - Gossip protocol crates
• saorsa-core - Core P2P library
• saorsa-node - Full network node