429725c4e1
Add comprehensive connection resilience implementation plan ( #4599 )
...
Added detailed multi-week implementation plan to CONNECTION_ARCHITECTURE.md with specific code implementations and prioritized roadmap for improving client-server connection reliability.
## Implementation Plan Overview
**Priority 1 (Week 1):** Critical fixes and diagnostics
- Fix Shardok security vulnerability (remove unauthenticated public access)
- Add comprehensive connection logging with structured metrics
- Reduce HTTP/2 keepalive to 15s for NAT traversal
**Priority 2 (Week 2):** State consistency and recovery
- Implement state resync mechanism with sequence numbers
- Add exponential backoff for reconnection attempts
- Create health monitoring UI for connection status visibility
**Priority 3 (Week 3):** Architecture improvements
- Consolidate heartbeat mechanisms (application-level + HTTP/2)
- Add circuit breaker pattern for cascading failure prevention
- Implement server-side metrics and monitoring
**Priority 4 (Week 4+):** Advanced features
- Adaptive keepalive parameters based on network conditions
- WebSocket fallback for environments with HTTP/2 issues
- Client-side prediction for improved UX during disconnections
## Includes
- Specific code implementations in C#, Scala, nginx, Python
- Complete testing strategy (unit, integration, load, manual)
- Success criteria with quantifiable metrics
- Monitoring & observability recommendations
- Security, performance, and rollback considerations
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-authored-by: Claude <noreply@anthropic.com >
2025-11-30 19:24:06 -08:00
98baf7ec66
Organize documentation into docs/ folder ( #4598 )
...
Create docs/ folder at repo root and move documentation files:
- CONNECTION_ARCHITECTURE.md (new comprehensive connection docs)
- COMMAND_PROTO_USAGE_ANALYSIS.md
- DEPROTO_PLAN.md
- SCALA3_MODERNIZATION.md
- actions-model-usage-analysis.md
- occupants-optimization-report.md
- scala3-reflection-issues.md
CLAUDE.md remains at root (project instructions for Claude Code).
Connection architecture documentation includes:
- gRPC bidirectional streaming protocol details
- Client-side connection management (PersistentClientConnection)
- Server-side implementation (EagleServiceImpl)
- nginx proxy configuration and timeouts
- Timeout settings across all layers (client, nginx, server)
- Eagle ↔ Shardok communication flow
Critical findings:
- 🔴 SECURITY: Shardok internal interface exposed without auth in nginx config
- Mystery "2-minute timeout" doesn't exist in code (all timeouts are 5-20 minutes)
- No state resync mechanism after connection drops during Shardok
- Inefficient dual-layer heartbeat (HTTP/2 + application level)
Hypotheses for remote player connection issues:
- Most likely: NAT/firewall timeout at player's router/ISP (60-120s)
- HTTP/2 keepalive (45s) may not be frequent enough to keep NAT alive
- Shardok's bursty traffic pattern may appear "idle" at transport layer
Recommendations:
1. Fix Shardok internal interface security vulnerability
2. Add precise connection drop logging with timestamps
3. Reduce HTTP/2 keepalive from 45s to 15s
4. Get network diagnostics from affected remote player
5. Implement state resync mechanism for Shardok
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-authored-by: Claude <noreply@anthropic.com >
2025-11-30 14:11:51 -08:00
