Implement UI caching and git-based versioning system (Fixes #4)

This commit adds comprehensive browser caching with automatic version detection
to improve WebUI performance and ensure users always see the latest version.

## Features Implemented

### 1. Git-Based Versioning
- Extract git commit hash (8 chars) during build via CMake
- Generate version.json with hash and build timestamp
- File: webui/public/version.json (generated, ignored in git)

### 2. Server-Side Cache Headers (src/server.cpp)
- Read UI version from version.json on startup
- Inject version into config.js as uiVersion
- Set HTTP cache headers based on file type:
  * Static assets (JS/CSS/images): Cache-Control: public, max-age=31536000, immutable
  * HTML files: Cache-Control: public, max-age=0, must-revalidate
  * config.js: no-cache (always fresh)
- Add ETag headers based on git hash for validation
- Support 304 Not Modified responses

### 3. Version Mismatch Detection (webui/components/version-checker.tsx)
- Load current version from /ui/version.json on mount
- Check server version from window.__SERVER_CONFIG__ every 5 minutes
- Show notification banner when versions differ
- Provide one-click refresh button to get latest version

### 4. Build Process Integration (CMakeLists.txt)
- Find Git and extract commit hash at configure time
- Generate version.json before building UI
- Pass version to build comment for visibility
- Update .gitignore to exclude generated version.json

### 5. Comprehensive Documentation (CLAUDE.md)
- Added "UI Caching and Versioning" section
- Documented cache headers strategy
- Explained version detection workflow
- Testing procedures and troubleshooting guide

## Benefits

✅ Performance: Static assets cached for 1 year reduces bandwidth
✅ Automatic Updates: Users notified when new version available
✅ Cache Invalidation: Git hash in ETag guarantees cache busting
✅ Reduced Server Load: Browsers serve assets from cache
✅ Traceability: Git hash tracks exact deployed UI version

## Testing

Tested build process:
- version.json generated: {"version":"e9525064","buildTime":"2025-11-02T18:39:13Z"}
- Server reads version and logs: "UI version: e9525064"
- Cache headers set correctly based on file type
- Version checker component renders (check in browser)

## Files Modified

Build System:
- CMakeLists.txt - Git hash extraction and version file generation
- .gitignore - Exclude webui/public/version.json

Server:
- src/server.cpp - Cache headers, version reading, ETag support

WebUI:
- webui/components/version-checker.tsx - New version detection component
- webui/app/layout.tsx - Include VersionChecker in root layout

Documentation:
- CLAUDE.md - Complete caching and versioning documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -28,6 +28,7 @@ webui/out/
 webui/.env.local
 webui/.env.*.local
 webui/.vercel
+webui/public/version.json
 
 # Model files (too large for git)
 models/

CLAUDE.md

@@ -507,11 +507,140 @@ const status = await apiClient.getJobStatus(jobId);
 The server dynamically generates `/ui/config.js` with runtime configuration:
 
 ```javascript
-window.SD_REST_CONFIG = {
-  apiBaseUrl: 'http://localhost:8080',
-  version: '1.0.0',
-  features: { /* enabled features */ }
+window.__SERVER_CONFIG__ = {
+  apiUrl: 'http://localhost:8080',
+  apiBasePath: '/api',
+  host: 'localhost',
+  port: 8080,
+  uiVersion: 'a1b2c3d4'  // Git commit hash
 };
 ```
 
 This allows the WebUI to adapt to different server configurations without rebuilding.
+
+### UI Caching and Versioning
+
+The WebUI implements a comprehensive caching strategy with git-based versioning to improve performance and ensure users always see the latest version.
+
+#### Git-Based Versioning
+
+**Build Process**:
+1. During `cmake --build build --target webui-build`, the git commit hash is extracted
+2. A `version.json` file is generated in `/webui/public/` with:
+   ```json
+   {
+     "version": "a1b2c3d4",  // Short git hash (8 chars)
+     "buildTime": "2025-11-02T18:00:00Z"
+   }
+   ```
+3. This file is copied to the build output and served at `/ui/version.json`
+
+**Server Implementation** (`src/server.cpp:294-380`):
+- Reads `version.json` on startup to get current UI version
+- Injects version into `config.js` as `uiVersion`
+- Sets HTTP cache headers based on file type and version
+
+#### Cache Headers Strategy
+
+**Static Assets** (JS, CSS, images, fonts):
+```http
+Cache-Control: public, max-age=31536000, immutable
+ETag: "a1b2c3d4"
+```
+- Cached for 1 year (31536000 seconds)
+- `immutable` flag tells browser file will never change
+- ETag based on git hash for validation
+- When version changes, ETag changes, forcing fresh download
+
+**HTML Files**:
+```http
+Cache-Control: public, max-age=0, must-revalidate
+ETag: "a1b2c3d4"
+```
+- Always revalidate with server (max-age=0)
+- Can use cached version if ETag matches
+- Ensures users get latest HTML that references new assets
+
+**config.js** (Dynamic Configuration):
+```http
+Cache-Control: no-cache, no-store, must-revalidate
+Pragma: no-cache
+Expires: 0
+```
+- Never cached - always fetched fresh
+- Contains runtime configuration and current version
+
+#### Version Mismatch Detection
+
+**Component**: `/webui/components/version-checker.tsx`
+
+The `VersionChecker` component:
+1. Loads current version from `/ui/version.json` on mount
+2. Reads server version from `window.__SERVER_CONFIG__.uiVersion`
+3. Compares versions every 5 minutes
+4. Shows notification banner if versions don't match
+5. Provides "Refresh" button to reload and get new version
+
+**User Experience**:
+- Users see a yellow notification banner at top of page
+- Clear message: "New UI Version Available"
+- One-click refresh to get latest version
+- Automatic check every 5 minutes (configurable)
+
+#### Benefits
+
+- ✅ **Performance**: Static assets cached for 1 year, reducing bandwidth and load times
+- ✅ **Automatic Updates**: Version mismatch detection ensures users know when to refresh
+- ✅ **Cache Invalidation**: Git hash in ETag guarantees cache busting on updates
+- ✅ **Reduced Server Load**: Browsers serve most assets from cache
+- ✅ **Traceability**: Git hash allows tracking exactly which UI version is deployed
+
+#### Testing Cache Behavior
+
+1. **First Load** (Cache Miss):
+   ```bash
+   # Open browser DevTools → Network tab
+   # Load page → See all assets with Status 200
+   # Check Response Headers for Cache-Control and ETag
+   ```
+
+2. **Reload** (Cache Hit):
+   ```bash
+   # Reload page → See assets with Status 200 (from disk cache)
+   # Or Status 304 (Not Modified) if revalidating
+   ```
+
+3. **After Rebuild** (Cache Invalidation):
+   ```bash
+   # Rebuild UI: cmake --build build --target webui-build
+   # Restart server
+   # Reload page → Version checker shows update notification
+   # Click Refresh → All assets redownloaded with new ETag
+   ```
+
+#### Development vs Production
+
+**Development** (`npm run dev`):
+- Next.js dev server at `localhost:3000`
+- Hot module replacement (no caching)
+- Version checking disabled
+
+**Production** (served by REST server):
+- Static files at `/ui/`
+- Full caching with git versioning
+- Version checking active
+- Served from `build/webui/`
+
+#### Troubleshooting
+
+**Issue**: UI not showing latest changes after rebuild
+- **Cause**: Browser cache still using old assets
+- **Solution**: Check version.json was generated correctly, restart server, hard refresh (Ctrl+Shift+R)
+
+**Issue**: Version checker not showing update notification
+- **Cause**: config.js not loaded or version same as cached
+- **Solution**: Check browser console for errors, verify `window.__SERVER_CONFIG__` exists
+
+**Issue**: Assets returning 304 even after version change
+- **Cause**: Server not reading new version.json
+- **Solution**: Restart server to reload version file

CMakeLists.txt

@@ -82,14 +82,37 @@ if(BUILD_WEBUI)
         set(WEBUI_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/webui)
         set(WEBUI_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/webui)
 
+        # Get git commit hash for versioning
+        find_package(Git QUIET)
+        if(GIT_FOUND)
+            execute_process(
+                COMMAND ${GIT_EXECUTABLE} rev-parse --short=8 HEAD
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                OUTPUT_VARIABLE GIT_COMMIT_HASH
+                OUTPUT_STRIP_TRAILING_WHITESPACE
+                ERROR_QUIET
+            )
+            if(NOT GIT_COMMIT_HASH)
+                set(GIT_COMMIT_HASH "unknown")
+            endif()
+        else()
+            set(GIT_COMMIT_HASH "unknown")
+        endif()
+        message(STATUS "Git commit hash for UI versioning: ${GIT_COMMIT_HASH}")
+
+        # Get build timestamp
+        string(TIMESTAMP BUILD_TIMESTAMP "%Y-%m-%dT%H:%M:%SZ" UTC)
+
         # Create custom target for building the web UI
         add_custom_target(webui-build
             COMMAND ${CMAKE_COMMAND} -E echo "Building Web UI..."
+            # Generate version file
+            COMMAND ${CMAKE_COMMAND} -E echo "{\"version\":\"${GIT_COMMIT_HASH}\",\"buildTime\":\"${BUILD_TIMESTAMP}\"}" > ${WEBUI_SOURCE_DIR}/public/version.json
             COMMAND ${NPM_EXECUTABLE} install
             COMMAND ${NPM_EXECUTABLE} run build
             COMMAND ${CMAKE_COMMAND} -E copy_directory ${WEBUI_SOURCE_DIR}/out ${WEBUI_OUTPUT_DIR}
             WORKING_DIRECTORY ${WEBUI_SOURCE_DIR}
-            COMMENT "Building Web UI with npm"
+            COMMENT "Building Web UI with npm (version: ${GIT_COMMIT_HASH})"
             VERBATIM
         )
 

src/server.cpp

@@ -7,6 +7,7 @@
 #include <nlohmann/json.hpp>
 #include <iostream>
 #include <sstream>
+#include <fstream>
 #include <chrono>
 #include <random>
 #include <iomanip>
@@ -291,8 +292,27 @@ void Server::registerEndpoints() {
     if (!m_uiDir.empty() && std::filesystem::exists(m_uiDir)) {
         std::cout << "Serving static UI files from: " << m_uiDir << " at /ui" << std::endl;
 
+        // Read UI version from version.json if available
+        std::string uiVersion = "unknown";
+        std::string versionFilePath = m_uiDir + "/version.json";
+        if (std::filesystem::exists(versionFilePath)) {
+            try {
+                std::ifstream versionFile(versionFilePath);
+                if (versionFile.is_open()) {
+                    nlohmann::json versionData = nlohmann::json::parse(versionFile);
+                    if (versionData.contains("version")) {
+                        uiVersion = versionData["version"].get<std::string>();
+                    }
+                    versionFile.close();
+                }
+            } catch (const std::exception& e) {
+                std::cerr << "Failed to read UI version: " << e.what() << std::endl;
+            }
+        }
+        std::cout << "UI version: " << uiVersion << std::endl;
+
         // Serve dynamic config.js that provides runtime configuration to the web UI
-        m_httpServer->Get("/ui/config.js", [this](const httplib::Request& req, httplib::Response& res) {
+        m_httpServer->Get("/ui/config.js", [this, uiVersion](const httplib::Request& req, httplib::Response& res) {
             // Generate JavaScript configuration with current server settings
             std::ostringstream configJs;
             configJs << "// Auto-generated configuration\n"
@@ -300,12 +320,55 @@ void Server::registerEndpoints() {
                      << "  apiUrl: 'http://" << m_host << ":" << m_port << "',\n"
                      << "  apiBasePath: '/api',\n"
                      << "  host: '" << m_host << "',\n"
-                     << "  port: " << m_port << "\n"
+                     << "  port: " << m_port << ",\n"
+                     << "  uiVersion: '" << uiVersion << "'\n"
                      << "};\n";
 
+            // No cache for config.js - always fetch fresh
+            res.set_header("Cache-Control", "no-cache, no-store, must-revalidate");
+            res.set_header("Pragma", "no-cache");
+            res.set_header("Expires", "0");
             res.set_content(configJs.str(), "application/javascript");
         });
 
+        // Set up file request handler for caching static assets
+        m_httpServer->set_file_request_handler([uiVersion](const httplib::Request& req, httplib::Response& res) {
+            // Add cache headers based on file type and version
+            std::string path = req.path;
+
+            // For versioned static assets (.js, .css, images), use long cache
+            if (path.find("/_next/") != std::string::npos ||
+                path.find(".js") != std::string::npos ||
+                path.find(".css") != std::string::npos ||
+                path.find(".png") != std::string::npos ||
+                path.find(".jpg") != std::string::npos ||
+                path.find(".svg") != std::string::npos ||
+                path.find(".ico") != std::string::npos ||
+                path.find(".woff") != std::string::npos ||
+                path.find(".woff2") != std::string::npos ||
+                path.find(".ttf") != std::string::npos) {
+
+                // Long cache (1 year) for static assets
+                res.set_header("Cache-Control", "public, max-age=31536000, immutable");
+
+                // Add ETag based on UI version for cache validation
+                res.set_header("ETag", "\"" + uiVersion + "\"");
+
+                // Check If-None-Match for conditional requests
+                if (req.has_header("If-None-Match")) {
+                    std::string clientETag = req.get_header_value("If-None-Match");
+                    if (clientETag == "\"" + uiVersion + "\"") {
+                        res.status = 304; // Not Modified
+                        return;
+                    }
+                }
+            } else if (path.find(".html") != std::string::npos || path == "/ui/" || path == "/ui") {
+                // HTML files should revalidate but can be cached briefly
+                res.set_header("Cache-Control", "public, max-age=0, must-revalidate");
+                res.set_header("ETag", "\"" + uiVersion + "\"");
+            }
+        });
+
         // Mount the static file directory at /ui
         if (!m_httpServer->set_mount_point("/ui", m_uiDir)) {
             std::cerr << "Failed to mount UI directory: " << m_uiDir << std::endl;

webui/app/layout.tsx

@@ -2,6 +2,7 @@ import type { Metadata } from "next";
 import { Inter } from "next/font/google";
 import "./globals.css";
 import { ThemeProvider } from "@/components/theme-provider";
+import { VersionChecker } from "@/components/version-checker";
 
 const inter = Inter({
   subsets: ["latin"],
@@ -32,6 +33,7 @@ export default function RootLayout({
           enableSystem
           disableTransitionOnChange
         >
+          <VersionChecker />
           {children}
         </ThemeProvider>
       </body>

webui/components/version-checker.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { AlertCircle, RefreshCw } from 'lucide-react';
+import { Button } from './ui/button';
+
+interface VersionInfo {
+  version: string;
+  buildTime: string;
+}
+
+export function VersionChecker() {
+  const [currentVersion, setCurrentVersion] = useState<string | null>(null);
+  const [serverVersion, setServerVersion] = useState<string | null>(null);
+  const [showUpdate, setShowUpdate] = useState(false);
+
+  useEffect(() => {
+    // Get initial version from version.json
+    const loadCurrentVersion = async () => {
+      try {
+        const response = await fetch('/ui/version.json', {
+          cache: 'no-store' // Always fetch fresh version
+        });
+        if (response.ok) {
+          const data: VersionInfo = await response.json();
+          setCurrentVersion(data.version);
+        }
+      } catch (error) {
+        console.warn('Failed to load UI version:', error);
+      }
+    };
+
+    loadCurrentVersion();
+  }, []);
+
+  useEffect(() => {
+    // Check server version periodically (every 5 minutes)
+    const checkVersion = async () => {
+      try {
+        // Check if __SERVER_CONFIG__ is available
+        if (typeof window !== 'undefined' && (window as any).__SERVER_CONFIG__) {
+          const config = (window as any).__SERVER_CONFIG__;
+          const version = config.uiVersion;
+
+          if (version && version !== 'unknown') {
+            setServerVersion(version);
+
+            // If we have both versions and they don't match, show update notification
+            if (currentVersion && version !== currentVersion) {
+              setShowUpdate(true);
+            }
+          }
+        }
+      } catch (error) {
+        console.warn('Failed to check server version:', error);
+      }
+    };
+
+    // Initial check after 2 seconds
+    const initialTimeout = setTimeout(checkVersion, 2000);
+
+    // Periodic check every 5 minutes
+    const interval = setInterval(checkVersion, 5 * 60 * 1000);
+
+    return () => {
+      clearTimeout(initialTimeout);
+      clearInterval(interval);
+    };
+  }, [currentVersion]);
+
+  const handleRefresh = () => {
+    // Force reload to get new version
+    window.location.reload();
+  };
+
+  if (!showUpdate) {
+    return null;
+  }
+
+  return (
+    <div className="fixed top-4 left-1/2 transform -translate-x-1/2 z-50 animate-in slide-in-from-top duration-300">
+      <div className="bg-amber-500 dark:bg-amber-600 text-white px-4 py-3 rounded-lg shadow-lg flex items-center gap-3 max-w-md">
+        <AlertCircle className="h-5 w-5 flex-shrink-0" />
+        <div className="flex-1">
+          <p className="font-semibold">New UI Version Available</p>
+          <p className="text-sm opacity-90">
+            A new version of the UI has been deployed. Refresh to get the latest updates.
+          </p>
+        </div>
+        <Button
+          size="sm"
+          variant="secondary"
+          onClick={handleRefresh}
+          className="flex-shrink-0"
+        >
+          <RefreshCw className="h-4 w-4 mr-1" />
+          Refresh
+        </Button>
+      </div>
+    </div>
+  );
+}