Skip to content

QUICKSTART.md

Latest commit

 

History

History
139 lines (100 loc) · 2.63 KB

QUICKSTART.md

File metadata and controls

139 lines (100 loc) · 2.63 KB
Raw

Quick Start - Test Your Broker

Follow these simple steps to test your distributed message broker:

✅ Step 1: Run Unit Tests

go test ./... -v

Expected output: All tests should pass ✅

✅ Step 2: Start the Broker

go run ./cmd/broker -id node-1

Expected output:

🚀 Starting Broker Node: node-1
   gRPC:    localhost:8080
   Raft:    localhost:9080
   Metrics: localhost:9090/metrics
📊 Metrics server started on :9090
✅ Server ready!

Leave this running! Open a new terminal for the next steps.

✅ Step 3: Run the Demo

In a new terminal:

go run ./examples/demo

Expected output:

🚀 Broker Demo
1️⃣  Creating topic 'demo-topic'...
2️⃣  Producing single messages...
   ✅ Produced message 0 at offset 0
3️⃣  Consuming messages...
   📖 Offset 0: Hello, World!
4️⃣  Batch producing 5 messages...
   ✅ Produced 5 records starting at offset 3
5️⃣  Batch consuming...
   📖 Consumed 5 records
6️⃣  Listing topics...
   📋 Topics: [demo-topic]
✅ Demo complete!

✅ Step 4: Check Metrics

Open in browser or use curl:

# Health check
curl http://localhost:9090/health

# Metrics
curl http://localhost:9090/metrics

🚀 Advanced: Test 3-Node Cluster

Terminal 1 (Leader):

go run ./cmd/broker -id node-1 -grpc-port 8080 -raft-port 9080

Terminal 2 (Follower 1):

go run ./cmd/broker -id node-2 -grpc-port 8081 -raft-port 9081 -join localhost:8080

Terminal 3 (Follower 2):

go run ./cmd/broker -id node-3 -grpc-port 8082 -raft-port 9082 -join localhost:8080

Test the cluster:

# Run demo (connects to node-1)
go run ./examples/demo

# Kill node-1 (Ctrl+C in Terminal 1)
# Wait ~5 seconds for leader election

# Demo still works with new leader!
go run ./examples/demo

📊 Performance Test

go test -v -run TestHighThroughput -timeout 2m

Troubleshooting

Problem: Demo fails with "connection refused"

  • Solution: Make sure broker is running first (Step 2)

Problem: Port already in use

  • Solution: Clean up: Remove-Item -Recurse -Force data

Problem: Tests fail

  • Solution: Stop all brokers, then: Remove-Item -Recurse -Force data

What You've Tested

  • ✅ Single message produce/consume
  • ✅ Batch operations
  • ✅ Topic management
  • ✅ Consumer groups (in unit tests)
  • ✅ Metrics & health checks
  • ✅ Raft consensus
  • ✅ Cluster join
  • ✅ Leader election & failover

For detailed testing instructions, see TESTING.md