[2026-04-28] Add apple-browsers .cursor rules (43 files) + executor v2 context

2026-04-28 00:30:19 +06:00
parent dac59f4cff
commit 639338eda3
44 changed files with 18230 additions and 0 deletions
@@ -0,0 +1,166 @@
+---
+source: ~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/network-quality-testing.mdc
+confidence: 0.9
+namespace: work
+last_synced: 2026-04-28
+alwaysApply: false
+---
+
+# NetworkQualityMonitor Testing Framework
+
+## Overview
+
+The NetworkQualityMonitor is a comprehensive network quality testing framework designed for the DuckDuckGo Privacy Browser. It provides pre-flight network connectivity and performance checks to ensure optimal browser performance.
+
+## Architecture Principles
+
+### SOLID Design
+- **Single Responsibility**: Each tester handles one specific network metric
+- **Open/Closed**: Protocol-based design allows extension without modification
+- **Dependency Injection**: All dependencies injected for testability
+- **Interface Segregation**: Focused protocols for each test type
+
+### Component Structure
+```
+NetworkQualityMonitor (Orchestrator)
+├── HttpResponseTester (Latency)
+├── BandwidthTester (Speed)
+├── DNSTester (Resolution)
+├── BufferBloatTester (Congestion)
+└── NetworkScoreCalculator (Scoring)
+```
+
+## Test Implementation Details
+
+### HTTP Response Testing (Latency)
+- **Multi-endpoint sampling**: Tests CDN endpoints (CloudFlare, Fastly, CloudFront)
+- **Statistical analysis**: Calculates median, mean, standard deviation, CV
+- **Smart aggregation**: Best site selection with weighted penalties
+- **Metrics**: P50/P95 percentiles, variance, failure rate
+
+### Bandwidth Testing
+- **Server selection**: Quick 10MB test, then full test on best servers
+- **Download measurement**: Multiple runs, returns maximum speed
+- **Upload measurement**: Chunked uploads (50MB x 2)
+- **Optimization**: Range requests, cache-busting, timeout protection
+
+### DNS Testing
+- **Domain resolution**: Popular domains (google.com, cloudflare.com)
+- **Timing precision**: CFAbsoluteTime for microsecond accuracy
+- **Failure tracking**: Resolution success/failure rates
+- **System resolver**: Uses native DNS resolution
+
+### Buffer Bloat Testing
+- **Baseline measurement**: Unloaded network latency
+- **Load testing**: Concurrent downloads during latency measurement
+- **Grade assignment**: A-F based on latency increase percentage
+- **Real-time impact**: Critical for video calls, gaming
+
+## Scoring Algorithm
+
+### Component Weights
+- HTTP Response: 25%
+- Bandwidth: 35%
+- DNS: 15%
+- Buffer Bloat: 25%
+
+### Quality Ratings
+- **Excellent (80-100)**: Optimal performance
+- **Good (60-79)**: Good for most tasks
+- **Fair (40-59)**: May experience issues
+- **Poor (0-39)**: Significant issues likely
+
+## Testing Best Practices
+
+### Unit Testing
+```swift
+// Use protocol-based mocks
+class MockHttpResponseTester: HttpResponseTesting {
+    func performTest(...) async throws -> HttpResponseResult {
+        // Return deterministic results
+    }
+}
+```
+
+### Integration Testing
+- Mock NetworkSession for controlled responses
+- Test error scenarios and edge cases
+- Verify progress callback behavior
+
+### Performance Testing
+- Monitor memory usage during large downloads
+- Verify timeout handling
+- Test concurrent execution
+
+## Usage Patterns
+
+### Basic Implementation
+```swift
+let monitor = NetworkQualityMonitor()
+let results = try await monitor.runTest()
+print("Quality: \(results.quality.rawValue)")
+```
+
+### With Progress Reporting
+```swift
+monitor.progressCallback = { progress, message in
+    // Update UI with progress
+}
+```
+
+### Custom Configuration
+```swift
+let config = TestConfiguration(
+    latencyTestURLs: customURLs,
+    latencySamplesPerEndpoint: 20
+)
+let monitor = NetworkQualityMonitor(configuration: config)
+```
+
+## Security Considerations
+
+- **HTTPS only**: All endpoints use secure connections
+- **No user data**: Only generic test payloads
+- **Certificate validation**: Standard validation enabled
+- **Rate limiting**: Built-in delays between samples
+
+## Error Handling
+
+### Error Types
+- `invalidResponse`: HTTP errors, malformed data
+- `allTestsFailed`: Complete connectivity loss
+- `insufficientData`: Not enough samples collected
+- `timeout`: Test exceeded time limit
+
+### Recovery Strategies
+- Continue testing if individual endpoints fail
+- Provide partial results when possible
+- Clear error reporting with localized descriptions
+
+## Performance Optimizations
+
+- **HEAD requests**: Minimal data for latency tests
+- **Range requests**: Efficient server selection
+- **Connection reuse**: URLSession connection pooling
+- **Memory streaming**: Large downloads streamed, not buffered
+
+## Package Integration
+
+### Adding to Project
+1. Add NetworkQualityMonitor package dependency
+2. Import NetworkQualityMonitor module
+3. Initialize with configuration
+4. Handle async test execution
+
+### Debug Menu Integration
+- Available under Debug → Network Quality
+- Individual test execution
+- Detailed result display
+
+## Future Enhancements
+
+- IPv6 testing separation
+- Jitter analysis
+- Packet loss detection
+- Geographic server selection
+- Historical trending