|
| 1 | +--- |
| 2 | +name: local-service-validation |
| 3 | +description: Comprehensive local service testing and validation capability for independent verification |
| 4 | +--- |
| 5 | + |
| 6 | +# Local Service Validation Skill |
| 7 | + |
| 8 | +## Purpose |
| 9 | +Provides comprehensive capability for local service testing and validation, eliminating dependency on external feedback for basic verification. |
| 10 | + |
| 11 | +## When to Use |
| 12 | +- Starting local servers (cargo run, npm start, etc.) |
| 13 | +- Need to verify if service started successfully |
| 14 | +- Testing local development environments |
| 15 | +- Validating port availability and HTTP responses |
| 16 | +- Monitoring local service status |
| 17 | + |
| 18 | +## Quick Validation Commands |
| 19 | + |
| 20 | +### 1. Port Status Check (5 seconds) |
| 21 | +```bash |
| 22 | +# Check if port 3000 is occupied |
| 23 | +netstat -an | grep :3000 |
| 24 | +# Alternative for different systems |
| 25 | +lsof -i :3000 |
| 26 | +ss -tulpn | grep :3000 |
| 27 | +``` |
| 28 | + |
| 29 | +### 2. HTTP Response Validation (5 seconds) |
| 30 | +```bash |
| 31 | +# Test local server response |
| 32 | +curl -I http://localhost:3000 |
| 33 | +# With timeout |
| 34 | +curl -I --connect-timeout 5 http://localhost:3000 |
| 35 | +# Full response test |
| 36 | +curl -s http://localhost:3000 | head -10 |
| 37 | +``` |
| 38 | + |
| 39 | +### 3. Process Monitoring (5 seconds) |
| 40 | +```bash |
| 41 | +# Check if Rust process is running |
| 42 | +ps aux | grep cargo |
| 43 | +# More specific |
| 44 | +pgrep -f "cargo run" |
| 45 | +# Process details |
| 46 | +ps aux | grep -E "(cargo|rust)" |
| 47 | +``` |
| 48 | + |
| 49 | +### 4. Log Monitoring (Real-time) |
| 50 | +```bash |
| 51 | +# Monitor server output with logging |
| 52 | +cargo run 2>&1 | tee server.log |
| 53 | +# Background with log file |
| 54 | +cargo run > server.log 2>&1 & |
| 55 | +# Tail existing logs |
| 56 | +tail -f server.log |
| 57 | +``` |
| 58 | + |
| 59 | +## Systematic Validation Workflow |
| 60 | + |
| 61 | +### Phase 1: Pre-Start Verification |
| 62 | +```bash |
| 63 | +# Check port availability |
| 64 | +netstat -an | grep :3000 || echo "Port 3000 available" |
| 65 | + |
| 66 | +# Verify project structure |
| 67 | +ls -la Cargo.toml src/main.rs |
| 68 | + |
| 69 | +# Check dependencies |
| 70 | +cargo check |
| 71 | +``` |
| 72 | + |
| 73 | +### Phase 2: Service Startup |
| 74 | +```bash |
| 75 | +# Start with logging |
| 76 | +cargo run 2>&1 | tee server.log & |
| 77 | +SERVER_PID=$! |
| 78 | + |
| 79 | +# Wait for startup |
| 80 | +sleep 3 |
| 81 | + |
| 82 | +# Verify process started |
| 83 | +ps -p $SERVER_PID > /dev/null && echo "Process running" || echo "Process failed" |
| 84 | +``` |
| 85 | + |
| 86 | +### Phase 3: Post-Start Validation |
| 87 | +```bash |
| 88 | +# Check port occupation |
| 89 | +netstat -an | grep :3000 && echo "Port occupied" || echo "Port free" |
| 90 | + |
| 91 | +# Test HTTP response |
| 92 | +HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 || echo "000") |
| 93 | +echo "HTTP Status: $HTTP_STATUS" |
| 94 | + |
| 95 | +# Full validation |
| 96 | +if [ "$HTTP_STATUS" = "200" ]; then |
| 97 | + echo "✅ Service validation successful" |
| 98 | +else |
| 99 | + echo "❌ Service validation failed" |
| 100 | + echo "Check logs: tail -10 server.log" |
| 101 | +fi |
| 102 | +``` |
| 103 | + |
| 104 | +## Automated Validation Script |
| 105 | + |
| 106 | +### Complete Validation Script |
| 107 | +```bash |
| 108 | +#!/bin/bash |
| 109 | +# Local Service Validation Script |
| 110 | +# Usage: ./validate_local_service.sh [port] [service_name] |
| 111 | + |
| 112 | +PORT=${1:-3000} |
| 113 | +SERVICE=${2:-"Rust Application"} |
| 114 | + |
| 115 | +echo "🔍 Local Service Validation" |
| 116 | +echo "=========================" |
| 117 | +echo "Service: $SERVICE" |
| 118 | +echo "Port: $PORT" |
| 119 | +echo "" |
| 120 | + |
| 121 | +# Pre-start checks |
| 122 | +echo "📋 Pre-Start Verification" |
| 123 | +echo "Port $PORT status:" |
| 124 | +netstat -an | grep :$PORT || echo "✅ Port available" |
| 125 | +echo "" |
| 126 | + |
| 127 | +# Start service |
| 128 | +echo "🚀 Starting Service" |
| 129 | +cargo run 2>&1 | tee server.log & |
| 130 | +SERVER_PID=$! |
| 131 | +echo "Started with PID: $SERVER_PID" |
| 132 | +echo "" |
| 133 | + |
| 134 | +# Wait for startup |
| 135 | +echo "⏳ Waiting for startup..." |
| 136 | +sleep 5 |
| 137 | +echo "" |
| 138 | + |
| 139 | +# Post-start validation |
| 140 | +echo "🔍 Post-Start Validation" |
| 141 | + |
| 142 | +# Process check |
| 143 | +if ps -p $SERVER_PID > /dev/null; then |
| 144 | + echo "✅ Process running (PID: $SERVER_PID)" |
| 145 | +else |
| 146 | + echo "❌ Process not running" |
| 147 | + exit 1 |
| 148 | +fi |
| 149 | + |
| 150 | +# Port check |
| 151 | +if netstat -an | grep :$PORT > /dev/null; then |
| 152 | + echo "✅ Port $PORT occupied" |
| 153 | +else |
| 154 | + echo "❌ Port $PORT not occupied" |
| 155 | +fi |
| 156 | + |
| 157 | +# HTTP check |
| 158 | +HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$PORT || echo "000") |
| 159 | +echo "HTTP Status: $HTTP_STATUS" |
| 160 | + |
| 161 | +if [ "$HTTP_STATUS" = "200" ]; then |
| 162 | + echo "✅ HTTP response successful" |
| 163 | + echo "🎉 Service validation COMPLETE" |
| 164 | +else |
| 165 | + echo "❌ HTTP response failed" |
| 166 | + echo "📋 Recent logs:" |
| 167 | + tail -10 server.log |
| 168 | +fi |
| 169 | +``` |
| 170 | + |
| 171 | +## Troubleshooting Framework |
| 172 | + |
| 173 | +### Issue 1: Port Already Occupied |
| 174 | +**Symptoms:** `netstat` shows port in use before starting |
| 175 | +**Solutions:** |
| 176 | +```bash |
| 177 | +# Find process using port |
| 178 | +lsof -i :3000 |
| 179 | +# Kill process |
| 180 | +kill -9 $(lsof -t -i :3000) |
| 181 | +# Try different port |
| 182 | +cargo run -- --port 3001 |
| 183 | +``` |
| 184 | + |
| 185 | +### Issue 2: Process Starts But No HTTP Response |
| 186 | +**Symptoms:** Process running but HTTP status 000 or connection refused |
| 187 | +**Solutions:** |
| 188 | +```bash |
| 189 | +# Check application logs |
| 190 | +tail -20 server.log |
| 191 | +# Verify binding address |
| 192 | +curl -I http://127.0.0.1:3000 |
| 193 | +# Check firewall |
| 194 | +sudo ufw status |
| 195 | +``` |
| 196 | + |
| 197 | +### Issue 3: Process Fails to Start |
| 198 | +**Symptoms:** Process not running after startup command |
| 199 | +**Solutions:** |
| 200 | +```bash |
| 201 | +# Check compilation errors |
| 202 | +cargo check |
| 203 | +# Verify dependencies |
| 204 | +cargo build |
| 205 | +# Check for syntax errors |
| 206 | +cargo run --verbose |
| 207 | +``` |
| 208 | + |
| 209 | +## Integration with Strategic Frameworks |
| 210 | + |
| 211 | +### Binary Truth Application |
| 212 | +- **Fact:** Port status (occupied/free) |
| 213 | +- **Fact:** HTTP response code (200/000/other) |
| 214 | +- **Fact:** Process status (running/not running) |
| 215 | +- **Avoid:** Speculation about "probably started" |
| 216 | + |
| 217 | +### Uncertainty Detection |
| 218 | +- **Trigger:** "I think it started" → "Let me verify" |
| 219 | +- **Action:** Run validation commands |
| 220 | +- **Result:** Binary fact about service status |
| 221 | + |
| 222 | +### Tool Building |
| 223 | +- **Create:** Reusable validation scripts |
| 224 | +- **Document:** Successful approaches |
| 225 | +- **Share:** Capability with other agents |
| 226 | + |
| 227 | +## Success Metrics |
| 228 | +- **Independence:** No user dependency for basic validation |
| 229 | +- **Speed:** Immediate status reporting (15 seconds total) |
| 230 | +- **Accuracy:** Verifiable facts about service status |
| 231 | +- **Reliability:** Consistent validation across different services |
| 232 | + |
| 233 | +## Related Capabilities |
| 234 | +- **Skill:** server-deployment-diagnostic (remote validation) |
| 235 | +- **Workflow:** 502-bad-gateway-resolution (systematic diagnosis) |
| 236 | +- **Rule:** uncertainty-to-investigation (validate assumptions) |
| 237 | +- **Memory:** self-validation-gap-local-testing (capability development) |
| 238 | + |
| 239 | +## Usage Examples |
| 240 | + |
| 241 | +### Basic Rust Server Validation |
| 242 | +```bash |
| 243 | +# Quick validation |
| 244 | +cargo run 2>&1 | tee server.log & |
| 245 | +sleep 3 |
| 246 | +curl -I http://localhost:3000 |
| 247 | +``` |
| 248 | + |
| 249 | +### Complete Validation |
| 250 | +```bash |
| 251 | +# Use automated script |
| 252 | +./validate_local_service.sh 3000 "Rust P2P Server" |
| 253 | +``` |
| 254 | + |
| 255 | +### Troubleshooting |
| 256 | +```bash |
| 257 | +# If validation fails |
| 258 | +tail -20 server.log |
| 259 | +netstat -an | grep :3000 |
| 260 | +ps aux | grep cargo |
| 261 | +``` |
0 commit comments