diff --git a/packages/wasm-sdk/CACHING.md b/packages/wasm-sdk/CACHING.md new file mode 100644 index 00000000000..21aec736267 --- /dev/null +++ b/packages/wasm-sdk/CACHING.md @@ -0,0 +1,146 @@ +# WASM SDK Caching + +The WASM SDK implements multiple caching strategies to improve performance and reduce network requests. + +## How Cache Invalidation Works + +The cache system uses two mechanisms to ensure users get updates: + +### 1. ETag Support (with server.py) + +When using `python3 server.py`: +- Server generates **ETags** based on file content +- Browser validates cache using ETags +- Returns `304 Not Modified` if unchanged +- Automatic cache invalidation when files change + +### 2. Cache-First with Background Updates + +The service worker: +- **Serves from cache immediately** (fast!) +- **Updates cache in background** +- Next reload gets the updated version +- No manual cache busting needed + +### How It Works + +1. **First visit**: Downloads and caches WASM files +2. **Subsequent visits**: Loads from cache instantly +3. **Background**: Checks for updates +4. **File changes**: New ETag → Cache updated +5. **Next visit**: New version served + +## Service Worker Caching + +The SDK uses a Service Worker to cache the WASM binary and JavaScript files. This provides: + +- **Offline capability**: Once cached, the SDK can work offline +- **Faster loading**: Subsequent visits load from cache instantly +- **Automatic updates**: The service worker checks for updates hourly + +### Files Cached + +- `/pkg/wasm_sdk.js` - JavaScript bindings +- `/pkg/wasm_sdk_bg.wasm` - WASM binary (several MB) +- `/pkg/wasm_sdk.d.ts` - TypeScript definitions +- `/index.html` - Main page + +## Using the Cache + +### Automatic Caching + +The service worker automatically caches files on first load. Subsequent loads will use the cached version. + +### Manual Cache Control + +The UI provides a "Clear Cache" button that: +1. Clears the service worker cache +2. Clears all browser caches +3. Reloads the page with fresh resources + +### Using the Python Server with Cache Headers + +For better cache control, use the provided Python server: + +```bash +# Instead of: +python3 -m http.server 8888 + +# Use: +python3 server.py +``` + +This server adds proper cache headers: +- WASM files: Cached for 1 week +- JS files in /pkg/: Cached for 1 week +- HTML files: Not cached +- Other files: Cached for 1 hour + +## Browser Developer Tips + +### Force Refresh +- **Chrome/Edge**: Ctrl+Shift+R (Cmd+Shift+R on Mac) +- **Firefox**: Ctrl+F5 (Cmd+Shift+R on Mac) +- **Safari**: Cmd+Option+R + +### Disable Cache in DevTools +1. Open Developer Tools (F12) +2. Go to Network tab +3. Check "Disable cache" + +### View Service Worker +1. Open Developer Tools +2. Go to Application tab +3. Click on "Service Workers" in sidebar +4. You can manually unregister the worker here + +## How It Works + +### Automatic Cache Updates + +1. **Build**: Just run `./build.sh` or `wasm-pack build` +2. **Deploy**: Upload the new files +3. **Automatic Detection**: Service worker detects the new WASM file hash +4. **User Notification**: Users see "New version detected!" +5. **Update**: Users refresh to get the new version + +### Example Flow + +```bash +# Make changes to Rust code +vim src/lib.rs + +# Build (cache updates automatically!) +./build.sh + +# That's it! No version increment needed +``` + +### Cache Names + +The cache is named based on content hash: +- `wasm-sdk-cache-a1b2c3d4` (old version) +- `wasm-sdk-cache-e5f6g7h8` (new version after rebuild) + +The service worker: +- Detects the hash changed +- Creates new cache with new name +- Deletes old cache +- Notifies users + +## Troubleshooting + +### Cache not working? +- Check if service worker registered (see console) +- Ensure HTTPS or localhost (service workers require secure context) +- Check browser support for service workers + +### Old version still loading? +1. Click "Clear Cache" button +2. Or manually unregister service worker in DevTools +3. Force refresh the page + +### Service worker errors? +- Check console for registration errors +- Ensure `/service-worker.js` is accessible +- Try incognito/private mode to bypass cache \ No newline at end of file diff --git a/packages/wasm-sdk/index.html b/packages/wasm-sdk/index.html index c188c223f93..54ae01aabfe 100644 --- a/packages/wasm-sdk/index.html +++ b/packages/wasm-sdk/index.html @@ -201,6 +201,20 @@ input:checked + .toggle-slider:before { transform: translateX(26px); } + + /* Style for SDK config details */ + details.sdk-config summary::-webkit-details-marker { + display: none; + } + + details.sdk-config[open] summary span:last-child { + transform: rotate(180deg); + transition: transform 0.2s; + } + + details.sdk-config summary span:last-child { + transition: transform 0.2s; + } .query-container { @@ -813,6 +827,48 @@

Dash Platform WASM JS SDK

+ +
+ + Advanced SDK Configuration + + +
+
+ +
+ + +
+ Leave empty for latest version +
+ +
+ Request Settings +
+ + +
+
+ + +
+
+ + +
+
+ +
+
+ + +
+
+