Commit e8b6d52
committed
docs(grpc): Add comprehensive documentation explaining why we use the fork
Adds WHY_USE_OPEN_RUNTIME_FORK.md (799 lines) that provides:
CONTEXT:
- Detailed explanation of ServerInterceptor dependency
- Complete mapping of codebase locations that depend on fork features
- Links to specific lines in both fork and monorepo code
- Production impact analysis with/without fork fixes
CRITICAL DEPENDENCIES DOCUMENTED:
1. ServerInterceptor class for security architecture
- EnhancedConnectionRejectionServerInterceptor (server.dart:1443-1540)
- Connection rejection tracking system (server.dart:775-1440)
- Progressive delay implementation (server.dart:1021-1070)
2. Race condition fixes for production stability
- Safe error handling (handler.dart:318-326)
- Safe trailer sending (handler.dart:404-410)
- Safe stream cleanup (handler.dart:442-450)
3. Null connection exception fix
- Clear error messages (http2_connection.dart:190-193)
- Defensive connection handling
4. Monorepo path dependencies
- Required by Melos architecture
- All packages reference ../../external_dependencies/grpc
USAGE EXAMPLES:
- Cloud Run server initialization (process.dart:723-732)
- JIT test server setup (test files)
- Connection tracking tests
COMPARISON MATRIX:
- Fork vs pub.dev feature availability
- Code locations that would break without fork
- Production impact scenarios
- Architecture dependency map
This documentation serves as reference for:
- Onboarding new developers
- Justifying fork maintenance cost
- Planning upstream sync strategy
- Understanding production requirements
Links to:
- Fork commit URLs
- Monorepo file locations with line numbers
- Upstream references
- Related documentation1 parent dedce7a commit e8b6d52
1 file changed
+799
-0
lines changed
0 commit comments