mleku/next.orly.dev
1
0
Fork 1
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Add NIP-11 relay synchronization and group management features
Some checks failed
Go / build (push) Has been cancelled
Details
Go / release (push) Has been cancelled
Details

Browse Source 
- Introduced a new `sync` package for managing NIP-11 relay information and relay group configurations.
- Implemented a cache for NIP-11 documents, allowing retrieval of relay public keys and authoritative configurations.
- Enhanced the sync manager to update peer lists based on authoritative configurations from relay group events.
- Updated event handling to incorporate policy checks during event imports, ensuring compliance with relay rules.
- Refactored various components to utilize the new `sha256-simd` package for improved performance.
- Added comprehensive tests to validate the new synchronization and group management functionalities.
- Bumped version to v0.24.1 to reflect these changes.
This commit is contained in:
mleku
2025-11-03 18:17:15 +00:00
parent e161d0e4be
commit e56bf76257
83 changed files with 3712 additions and 7417 deletions
Download Patch File Download Diff File Expand all files Collapse all files

617
docs/RELAY_TESTING_GUIDE.md Normal file
View File

@@ -0,0 +1,617 @@
# Relay Testing Guide
This guide explains how to use ORLY's comprehensive testing infrastructure for protocol validation, especially when developing features that require multiple relays to test the Nostr protocol correctly.
## Overview
ORLY provides multiple testing tools and scripts designed for different testing scenarios:
- **relay-tester**: Protocol compliance testing against NIP specifications
- **Benchmark suite**: Performance testing across multiple relay implementations
- **Policy testing**: Custom policy validation
- **Integration scripts**: Multi-relay testing scenarios
## Testing Tools Overview
### relay-tester
The primary tool for testing Nostr protocol compliance:
```bash
# Basic usage
relay-tester -url ws://127.0.0.1:3334
# Test with different configurations
relay-tester -url wss://relay.example.com -v -json
```
**Key Features:**
- Tests all major NIP-01, NIP-09, NIP-42 features
- Validates event publishing, querying, and subscription handling
- Checks JSON compliance and signature validation
- Provides both human-readable and JSON output
### Benchmark Suite
Performance testing across multiple relay implementations:
```bash
# Setup external relays
cd cmd/benchmark
./setup-external-relays.sh
# Run benchmark suite
docker-compose up --build
```
**Key Features:**
- Compares ORLY against other relay implementations
- Tests throughput, latency, and reliability
- Provides detailed performance metrics
- Generates comparison reports
### Policy Testing
Custom policy validation tools:
```bash
# Test policy with sample events
./scripts/run-policy-test.sh
# Test policy filter integration
./scripts/run-policy-filter-test.sh
```
## Multi-Relay Testing Scenarios
### Why Multiple Relays?
Many Nostr protocol features require testing with multiple relays:
- **Event replication** between relays
- **Cross-relay subscriptions** and queries
- **Relay discovery** and connection management
- **Protocol interoperability** between different implementations
- **Distributed features** like directory consensus
### Testing Infrastructure
ORLY provides several ways to run multiple relays for testing:
#### 1. Local Multi-Relay Setup
Run multiple instances on different ports:
```bash
# Terminal 1: Relay 1 on port 3334
ORLY_PORT=3334 ./orly &
# Terminal 2: Relay 2 on port 3335
ORLY_PORT=3335 ./orly &
# Terminal 3: Relay 3 on port 3336
ORLY_PORT=3336 ./orly &
```
#### 2. Docker-based Multi-Relay
Use Docker for isolated relay instances:
```bash
# Run multiple relays with Docker
docker run -d -p 3334:3334 -e ORLY_PORT=3334 orly:latest
docker run -d -p 3335:3334 -e ORLY_PORT=3334 orly:latest
docker run -d -p 3336:3334 -e ORLY_PORT=3334 orly:latest
```
#### 3. Benchmark Suite Multi-Relay
The benchmark suite automatically sets up multiple relays:
```bash
cd cmd/benchmark
./setup-external-relays.sh
docker-compose up next-orly khatru-sqlite strfry
```
## Developing Features Requiring Multiple Relays
### 1. Event Replication Testing
Test how events propagate between relays:
```go
// Example test for event replication
func TestEventReplication(t *testing.T) {
// Start two relays
relay1 := startTestRelay(t, 3334)
defer relay1.Stop()
relay2 := startTestRelay(t, 3335)
defer relay2.Stop()
// Connect clients to both relays
client1 := connectToRelay(t, "ws://127.0.0.1:3334")
client2 := connectToRelay(t, "ws://127.0.0.1:3335")
// Publish event to relay1
event := createTestEvent(t)
ok := client1.Publish(event)
assert.True(t, ok)
// Wait for replication/propagation
time.Sleep(100 * time.Millisecond)
// Query relay2 for the event
events := client2.Query(filterForEvent(event.ID))
assert.Len(t, events, 1)
assert.Equal(t, event.ID, events[0].ID)
}
```
### 2. Cross-Relay Subscriptions
Test subscriptions that span multiple relays:
```go
func TestCrossRelaySubscriptions(t *testing.T) {
// Setup multiple relays
relays := setupMultipleRelays(t, 3)
defer stopRelays(t, relays)
clients := connectToRelays(t, relays)
// Subscribe to same filter on all relays
filter := Filter{Kinds: []int{1}, Limit: 10}
for _, client := range clients {
client.Subscribe(filter)
}
// Publish events to different relays
for i, client := range clients {
event := createTestEvent(t)
event.Content = fmt.Sprintf("Event from relay %d", i)
client.Publish(event)
}
// Verify events appear on all relays (if replication is enabled)
time.Sleep(200 * time.Millisecond)
for _, client := range clients {
events := client.GetReceivedEvents()
assert.GreaterOrEqual(t, len(events), 3) // At least the events from all relays
}
}
```
### 3. Relay Discovery Testing
Test relay list events and dynamic relay discovery:
```go
func TestRelayDiscovery(t *testing.T) {
relay1 := startTestRelay(t, 3334)
relay2 := startTestRelay(t, 3335)
defer relay1.Stop()
defer relay2.Stop()
client := connectToRelay(t, "ws://127.0.0.1:3334")
// Publish relay list event (kind 10002)
relayList := createRelayListEvent(t, []string{
"wss://relay1.example.com",
"wss://relay2.example.com",
})
client.Publish(relayList)
// Test that relay discovery works
discovered := client.QueryRelays()
assert.Contains(t, discovered, "wss://relay1.example.com")
assert.Contains(t, discovered, "wss://relay2.example.com")
}
```
## Testing Scripts and Automation
### Automated Multi-Relay Testing
Use the provided scripts for automated testing:
#### 1. relaytester-test.sh
Tests relay with protocol compliance:
```bash
# Test single relay
./scripts/relaytester-test.sh
# Test with policy enabled
ORLY_POLICY_ENABLED=true ./scripts/relaytester-test.sh
# Test with ACL enabled
ORLY_ACL_MODE=follows ./scripts/relaytester-test.sh
```
#### 2. test.sh (Full Test Suite)
Runs all tests including multi-component scenarios:
```bash
# Run complete test suite
./scripts/test.sh
# Run specific package tests
go test ./pkg/sync/... # Test synchronization features
go test ./pkg/protocol/... # Test protocol implementations
```
#### 3. runtests.sh (Performance Tests)
```bash
# Run performance benchmarks
./scripts/runtests.sh
```
### Custom Testing Scripts
Create custom scripts for specific multi-relay scenarios:
```bash
#!/bin/bash
# test-multi-relay-replication.sh
# Start multiple relays
echo "Starting relays..."
ORLY_PORT=3334 ./orly &
RELAY1_PID=$!
ORLY_PORT=3335 ./orly &
RELAY2_PID=$!
ORLY_PORT=3336 ./orly &
RELAY3_PID=$!
# Wait for startup
sleep 2
# Run replication tests
echo "Running replication tests..."
go test -v ./pkg/sync -run TestReplication
# Run protocol tests
echo "Running protocol tests..."
relay-tester -url ws://127.0.0.1:3334 -json > relay1-results.json
relay-tester -url ws://127.0.0.1:3335 -json > relay2-results.json
relay-tester -url ws://127.0.0.1:3336 -json > relay3-results.json
# Cleanup
kill $RELAY1_PID $RELAY2_PID $RELAY3_PID
echo "Tests completed"
```
## Testing Distributed Features
### Directory Consensus Testing
Test NIP-XX directory consensus protocol:
```go
func TestDirectoryConsensus(t *testing.T) {
// Setup multiple relays with directory support
relays := setupDirectoryRelays(t, 5)
defer stopRelays(t, relays)
clients := connectToRelays(t, relays)
// Create trust acts between relays
for i, client := range clients {
trustAct := createTrustAct(t, client.Pubkey, relays[(i+1)%len(relays)].Pubkey, 80)
client.Publish(trustAct)
}
// Wait for consensus
time.Sleep(1 * time.Second)
// Verify trust relationships
for _, client := range clients {
trustGraph := client.QueryTrustGraph()
// Verify expected trust relationships exist
assert.True(t, len(trustGraph.GetAllTrustActs()) > 0)
}
}
```
### Sync Protocol Testing
Test event synchronization between relays:
```go
func TestRelaySynchronization(t *testing.T) {
relay1 := startTestRelay(t, 3334)
relay2 := startTestRelay(t, 3335)
defer relay1.Stop()
defer relay2.Stop()
// Enable sync between relays
configureSync(t, relay1, relay2)
client1 := connectToRelay(t, "ws://127.0.0.1:3334")
client2 := connectToRelay(t, "ws://127.0.0.1:3335")
// Publish events to relay1
events := createTestEvents(t, 100)
for _, event := range events {
client1.Publish(event)
}
// Wait for sync
waitForSync(t, relay1, relay2)
// Verify events on relay2
syncedEvents := client2.Query(Filter{Kinds: []int{1}, Limit: 200})
assert.Len(t, syncedEvents, 100)
}
```
## Performance Testing with Multiple Relays
### Load Testing
Test performance under load with multiple relays:
```bash
# Start multiple relays
for port in 3334 3335 3336; do
ORLY_PORT=$port ./orly &
echo $! >> relay_pids.txt
done
# Run load tests against each relay
for port in 3334 3335 3336; do
echo "Testing relay on port $port"
relay-tester -url ws://127.0.0.1:$port -json > results_$port.json &
done
wait
# Analyze results
# Combine and compare performance across relays
```
### Benchmarking Comparisons
Use the benchmark suite for comparative testing:
```bash
cd cmd/benchmark
# Setup all relay types
./setup-external-relays.sh
# Run benchmarks comparing multiple implementations
docker-compose up --build
# Results in reports/run_YYYYMMDD_HHMMSS/
cat reports/run_*/aggregate_report.txt
```
## Debugging Multi-Relay Issues
### Logging
Enable detailed logging for multi-relay debugging:
```bash
# Enable debug logging
export ORLY_LOG_LEVEL=debug
export ORLY_LOG_TO_STDOUT=true
# Start relays with logging
ORLY_PORT=3334 ./orly 2>&1 | tee relay1.log &
ORLY_PORT=3335 ./orly 2>&1 | tee relay2.log &
```
### Connection Monitoring
Monitor WebSocket connections between relays:
```bash
# Monitor network connections
netstat -tlnp | grep :3334
ss -tlnp | grep :3334
# Monitor relay logs
tail -f relay1.log | grep -E "(connect|disconnect|sync)"
```
### Event Tracing
Trace events across multiple relays:
```go
func traceEventPropagation(t *testing.T, eventID string, relays []*TestRelay) {
for _, relay := range relays {
client := connectToRelay(t, relay.URL)
events := client.Query(Filter{IDs: []string{eventID}})
if len(events) > 0 {
t.Logf("Event %s found on relay %s", eventID, relay.URL)
} else {
t.Logf("Event %s NOT found on relay %s", eventID, relay.URL)
}
}
}
```
## CI/CD Integration
### GitHub Actions Example
```yaml
# .github/workflows/multi-relay-tests.yml
name: Multi-Relay Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Go
uses: actions/setup-go@v4
with:
go-version: '1.21'
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y docker.io docker-compose
- name: Run single relay tests
run: ./scripts/relaytester-test.sh
- name: Run multi-relay integration tests
run: |
# Start multiple relays
ORLY_PORT=3334 ./orly &
ORLY_PORT=3335 ./orly &
ORLY_PORT=3336 ./orly &
sleep 3
# Run integration tests
go test -v ./pkg/sync -run TestMultiRelay
- name: Run benchmark suite
run: |
cd cmd/benchmark
./setup-external-relays.sh
docker-compose up --build --abort-on-container-exit
- name: Upload test results
uses: actions/upload-artifact@v3
with:
name: test-results
path: |
cmd/benchmark/reports/
*-results.json
```
## Best Practices
### 1. Test Isolation
- Use separate databases for each test relay
- Clean up resources after tests
- Use unique ports to avoid conflicts
### 2. Timing Considerations
- Allow time for event propagation between relays
- Use exponential backoff for retry logic
- Account for network latency in assertions
### 3. Resource Management
- Limit concurrent relays in CI/CD
- Clean up Docker containers and processes
- Monitor resource usage during tests
### 4. Error Handling
- Test both success and failure scenarios
- Verify error propagation across relays
- Test network failure scenarios
### 5. Performance Monitoring
- Measure latency between relays
- Track memory and CPU usage
- Monitor WebSocket connection stability
## Troubleshooting Common Issues
### Connection Failures
```bash
# Check if relays are listening
netstat -tlnp | grep :3334
# Test WebSocket connection manually
websocat ws://127.0.0.1:3334
```
### Event Propagation Delays
```bash
# Increase wait times in tests
time.Sleep(500 * time.Millisecond)
// Or use polling
func waitForEvent(t *testing.T, client *Client, eventID string) {
timeout := time.After(5 * time.Second)
ticker := time.NewTicker(100 * time.Millisecond)
defer ticker.Stop()
for {
select {
case <-timeout:
t.Fatalf("Event %s not found within timeout", eventID)
case <-ticker.C:
events := client.Query(Filter{IDs: []string{eventID}})
if len(events) > 0 {
return
}
}
}
}
```
### Race Conditions
```go
// Use proper synchronization
var mu sync.Mutex
eventCount := 0
// In test goroutines
mu.Lock()
eventCount++
mu.Unlock()
```
### Resource Exhaustion
```bash
# Limit relay instances in tests
const maxRelays = 3
func setupLimitedRelays(t *testing.T, count int) []*TestRelay {
if count > maxRelays {
t.Skipf("Skipping test requiring %d relays (max %d)", count, maxRelays)
}
// Setup relays...
}
```
## Contributing
When adding new features that require multi-relay testing:
1. Add unit tests for single-relay scenarios
2. Add integration tests for multi-relay scenarios
3. Update this guide with new testing patterns
4. Ensure tests work in CI/CD environment
5. Document any new testing tools or scripts
## Related Documentation
- [POLICY_USAGE_GUIDE.md](POLICY_USAGE_GUIDE.md) - Policy system testing
- [README.md](../../README.md) - Main project documentation
- [cmd/benchmark/README.md](../../cmd/benchmark/README.md) - Benchmark suite
- [cmd/relay-tester/README.md](../../cmd/relay-tester/README.md) - Protocol testing
This guide provides the foundation for testing complex Nostr protocol features that require multiple relay coordination. The testing infrastructure is designed to be extensible and support various testing scenarios while maintaining reliability and performance.