1# Research: WebKit Memory Optimization
2
3**Feature**: 005-webkit-memory-optimization
4**Phase**: 0 - Research & Technical Decisions
5**Date**: 2025-01-10
6
7## Technical Decisions Made
8
9### WebKit Memory Pressure API Selection
10**Decision**: Use WebKitMemoryPressureSettings introduced in WebKit2GTK 6.0
11**Rationale**: 
12- Provides granular control over memory limits and cleanup thresholds
13- Native WebKit memory management rather than external process monitoring
14- Integrates with WebKit's internal memory pressure signals
15- Available in WebKit2GTK 6.0+ (already required by project)
16
17**Alternatives considered**:
18- Manual process monitoring via /proc filesystem: Less integrated, more overhead
19- System-level memory pressure (systemd, kernel): Too coarse-grained for per-WebView control
20- JavaScript-only GC triggers: Insufficient for WebKit native memory (images, CSS, DOM)
21
22### Cache Model Optimization Strategy
23**Decision**: Use WEBKIT_CACHE_MODEL_DOCUMENT_VIEWER as memory-optimized default
24**Rationale**:
25- Minimal memory caching strategy designed for document viewing
26- 40-60% less memory usage than WEBKIT_CACHE_MODEL_WEB_BROWSER
27- Still maintains reasonable performance for typical browsing
28- Configurable - users can choose more performance-oriented models
29
30**Alternatives considered**:
31- Custom cache implementation: Too complex, reinvents WebKit internals
32- Disable all caching: Would break many websites and hurt performance significantly
33- Dynamic cache model switching: Added complexity without clear benefits
34
35### Process Recycling Implementation
36**Decision**: Track page load count per WebView, recommend recycling at configurable threshold
37**Rationale**:
38- WebKit processes accumulate memory over time due to fragmentation
39- Simple counter-based approach is reliable and predictable
40- User/application controls recycling policy, not automatic termination
41- Preserves user experience while managing long-term memory growth
42
43**Alternatives considered**:
44- Time-based recycling: Unpredictable memory impact, could interrupt user workflows
45- Memory-threshold recycling: More complex, could lead to recycling loops
46- Automatic process termination: Too aggressive, would lose user state
47
48### Memory Monitoring Architecture
49**Decision**: Hybrid approach using /proc filesystem + WebKit memory pressure callbacks
50**Rationale**:
51- /proc provides detailed RSS/VmSize metrics for external monitoring tools
52- WebKit callbacks provide internal memory pressure events
53- Both together give complete picture for debugging and optimization
54- Enables both real-time monitoring and historical tracking
55
56**Alternatives considered**:
57- WebKit-only monitoring: Limited visibility into actual system memory usage
58- /proc-only monitoring: Misses WebKit internal memory pressure states
59- External monitoring tools: Adds dependencies, complicates deployment
60
61### Configuration Preset Strategy
62**Decision**: Provide three preset configurations (memory-optimized, balanced, performance)
63**Rationale**:
64- Covers main use cases: low-memory devices, general use, high-performance needs
65- Simple choice for users, comprehensive under the hood
66- Provides sensible defaults while allowing customization
67- Aligns with constitutional simplicity requirements
68
69**Alternatives considered**:
70- Single configuration: Too rigid, doesn't accommodate different hardware/needs
71- Extensive customization UI: Too complex, violates constitutional simplicity
72- Auto-detection: Unpredictable, users prefer explicit control
73
74## Implementation Technologies Confirmed
75
76### Core Technologies
77- **WebKit2GTK 6.0**: Memory pressure settings, cache model control, JavaScript GC triggers
78- **GTK4**: Event handling, settings management (already in use)
79- **Go 1.25.1 + CGO**: C API bindings for WebKit memory features
80- **GLib/GObject**: Memory management, signal handling for WebKit callbacks
81
82### Testing Technologies
83- **Go testing**: Unit tests for configuration validation, memory calculations
84- **Integration testing**: Real WebKit processes, actual memory measurement
85- **Contract testing**: WebKit C API contract verification
86- **Performance testing**: Memory usage benchmarking, garbage collection impact
87
88### Monitoring Technologies
89- **/proc filesystem**: RSS, VmSize, VmPeak memory metrics
90- **WebKit memory pressure callbacks**: Internal memory state changes
91- **Go log package**: Structured logging for memory events
92- **Time-based metrics**: GC frequency, process lifecycle tracking
93
94## Best Practices Research
95
96### WebKit Memory Management Patterns
97- **Memory pressure thresholds**: Conservative (20-33%), Strict (35-50%), Kill (70-80%)
98- **Cache model hierarchy**: DocumentViewer < WebBrowser < PrimaryWebBrowser
99- **GC trigger frequency**: 30-120 second intervals optimal for background cleanup
100- **Process recycling**: 25-100 page loads typical before fragmentation impact
101
102### CGO Memory Safety Patterns
103- **Finalizers**: Set on WebView structs to cleanup native resources
104- **Reference counting**: Proper release of WebKit objects via g_object_unref
105- **String handling**: CString/free pairs, defer cleanup patterns
106- **Callback safety**: Store Go pointers safely for C callback functions
107
108### Performance Impact Mitigation
109- **Lazy configuration**: Apply memory settings only when explicitly requested
110- **Background operations**: GC and monitoring in separate goroutines
111- **Graceful degradation**: Fallback to defaults if memory APIs unavailable
112- **User control**: Make all optimizations opt-in to preserve existing performance
113
114## Risk Assessment
115
116### Low Risk
117- Configuration storage and validation (standard Go patterns)
118- Memory monitoring (/proc parsing is well-established)
119- Preset configurations (simple struct initialization)
120
121### Medium Risk
122- WebKit memory pressure integration (newer API, potential version compatibility)
123- Process recycling coordination (timing and state management complexity)
124- CGO callback handling (requires careful pointer management)
125
126### High Risk
127- Aggressive memory limits causing browser instability
128- Performance degradation from excessive GC or monitoring
129- Memory pressure false positives leading to unnecessary cleanup
130
131### Mitigation Strategies
132- Comprehensive integration testing with real websites
133- Conservative default values with gradual optimization options
134- Extensive logging and monitoring to detect issues early
135- Graceful fallback when memory optimization fails
136
137## Unknowns Resolved
138✅ All technical unknowns from Phase 0 resolved
139✅ WebKit2GTK 6.0 memory APIs researched and confirmed available
140✅ CGO integration patterns established for memory management
141✅ Testing approach defined for memory-related features
142✅ Performance impact mitigation strategies identified