#4 Add caching and versioning for built-in WebUI assets

Description

The built-in WebUI currently lacks proper browser caching and versioning, which can lead to:

• Unnecessary network requests on every page load
• Users seeing stale cached UI after updates
• Poor performance especially on slower connections

Proposed Solution

Implement a comprehensive caching strategy with git-based versioning:

1. Git Commit Hash Versioning

• Extract git commit hash during build time
• Store hash in a version file accessible to both server and UI
• Use short hash (8 chars) for version identifier

2. Server-Side Cache Headers

• Add cache-control headers for UI assets
• Implement ETag support based on git hash
• Set long cache times (1 year) for versioned assets
• Force revalidation when version changes

3. UI Version Detection

• Include version in UI config endpoint
• Check version on page load
• Auto-refresh UI when version mismatch detected

4. Build Process Integration

• CMake target to capture git hash
• Generate version file during webui-build
• Include version in compiled assets

Benefits

• ✅ Faster page loads (assets cached)
• ✅ Automatic cache invalidation on updates
• ✅ Better user experience
• ✅ Reduced server bandwidth
• ✅ Easy rollback detection (by commit hash)

Implementation Files

• /src/server.cpp - Cache headers and version endpoint
• /CMakeLists.txt - Git hash extraction during build
• /webui/lib/version.ts - Version checking utilities
• /webui/public/ - Asset serving with versioning

Testing

• Verify assets are cached on first load
• Confirm cache invalidation after rebuild
• Test version mismatch detection
• Check cache headers in browser DevTools

Implemented in commit 13c8d19.

Summary

Comprehensive UI caching and versioning system now fully functional using git commit hashes for automatic cache invalidation.

Implementation Details

Git-Based Versioning

• Build: Git hash extracted during cmake --build build --target webui-build

• Version File: /webui/public/version.json generated with:

  {"version":"e9525064","buildTime":"2025-11-02T18:39:13Z"}
  

• Current Version: e9525064 (based on current commit)

Cache Headers (Server-Side)

Static Assets (JS, CSS, images, fonts):

Cache-Control: public, max-age=31536000, immutable
ETag: "e9525064"

• Cached for 1 year
• ETag ensures cache invalidation when version changes

HTML Files:

Cache-Control: public, max-age=0, must-revalidate  
ETag: "e9525064"

• Always revalidate with server
• Can use cached version if ETag matches

config.js:

Cache-Control: no-cache, no-store, must-revalidate

• Never cached - always fresh

Version Detection (Client-Side)

• Component: VersionChecker in root layout
• Behavior: Checks version every 5 minutes
• UX: Yellow notification banner with "Refresh" button when update available
• Smart: Only shows notification when server version ≠ client version

Testing Results

✅ Build Process: version.json generated correctly
✅ Server Startup: Reads version and logs "UI version: e9525064"
✅ Cache Headers: Set correctly based on file type
✅ Version Component: Renders and checks periodically
✅ Cache Validation: ETags working for 304 responses

How to Use

1. Normal Operation: Assets cached, fast page loads

2. After Rebuild:

   • Rebuild UI: cmake --build build --target webui-build
   • Restart server
   • Users see update notification on next version check
   • Click "Refresh" to get new version

3. Verify in Browser:

   • Open DevTools → Network tab
   • Check Response Headers for Cache-Control and ETag
   • Reload page → See assets with Status 200 (disk cache) or 304 (not modified)

Documentation

Complete documentation added to CLAUDE.md covering:

• Build process and versioning
• Cache headers strategy
• Version detection workflow
  
• Testing procedures
• Troubleshooting guide