@xiboplayer/cache 0.3.1 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/cache",
-  "version": "0.3.1",
+  "version": "0.3.5",
   "description": "Offline caching and download management with parallel chunk downloads",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "spark-md5": "^3.0.2",
-    "@xiboplayer/utils": "0.3.1"
+    "@xiboplayer/utils": "0.3.5"
   },
   "devDependencies": {
     "vitest": "^2.0.0",

package/src/cache-analyzer.js

@@ -0,0 +1,189 @@
+/**
+ * CacheAnalyzer - Stale media detection and storage health monitoring
+ *
+ * Compares cached files against RequiredFiles from the CMS to identify
+ * orphaned media that is no longer needed. Logs a summary every collection
+ * cycle. Only evicts when storage pressure exceeds a configurable threshold.
+ */
+
+import { createLogger } from '@xiboplayer/utils';
+
+const log = createLogger('CacheAnalyzer');
+
+/**
+ * Format bytes into human-readable string (e.g. 1.2 GB, 350 MB)
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  if (!Number.isFinite(bytes)) return '∞';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const value = bytes / Math.pow(1024, i);
+  return `${value.toFixed(i > 0 ? 1 : 0)} ${units[i]}`;
+}
+
+export class CacheAnalyzer {
+  /**
+   * @param {import('./cache.js').CacheManager} cache - CacheManager instance
+   * @param {object} [options]
+   * @param {number} [options.threshold=80] - Storage usage % above which eviction triggers
+   */
+  constructor(cache, { threshold = 80 } = {}) {
+    this.cache = cache;
+    this.threshold = threshold;
+  }
+
+  /**
+   * Analyze cache health by comparing cached files against required files.
+   *
+   * @param {Array<{id: string, type: string}>} requiredFiles - Current RequiredFiles from CMS
+   * @returns {Promise<object>} Analysis report
+   */
+  async analyze(requiredFiles) {
+    const cachedFiles = await this.cache.getAllFiles();
+    const storage = await this._getStorageEstimate();
+
+    // Build set of required file IDs (as strings for consistent comparison)
+    const requiredIds = new Set(requiredFiles.map(f => String(f.id)));
+
+    // Categorize cached files
+    const required = [];
+    const orphaned = [];
+
+    for (const file of cachedFiles) {
+      if (requiredIds.has(String(file.id))) {
+        required.push(file);
+      } else {
+        orphaned.push(file);
+      }
+    }
+
+    // Sort orphaned by cachedAt ascending (oldest first — evict these first)
+    orphaned.sort((a, b) => (a.cachedAt || 0) - (b.cachedAt || 0));
+
+    const orphanedSize = orphaned.reduce((sum, f) => sum + (f.size || 0), 0);
+
+    const report = {
+      timestamp: Date.now(),
+      storage: {
+        usage: storage.usage,
+        quota: storage.quota,
+        percent: storage.quota > 0 ? Math.round((storage.usage / storage.quota) * 100) : 0,
+      },
+      files: {
+        required: required.length,
+        orphaned: orphaned.length,
+        total: cachedFiles.length,
+      },
+      orphaned: orphaned.map(f => ({
+        id: f.id,
+        type: f.type,
+        size: f.size || 0,
+        cachedAt: f.cachedAt || 0,
+      })),
+      orphanedSize,
+      evicted: [],
+      threshold: this.threshold,
+    };
+
+    // Log summary
+    log.info(`Storage: ${formatBytes(storage.usage)} / ${formatBytes(storage.quota)} (${report.storage.percent}%)`);
+    log.info(`Cache: ${required.length} required, ${orphaned.length} orphaned (${formatBytes(orphanedSize)} reclaimable)`);
+
+    if (orphaned.length > 0) {
+      for (const f of orphaned) {
+        const age = Date.now() - (f.cachedAt || 0);
+        const days = Math.floor(age / 86400000);
+        const hours = Math.floor((age % 86400000) / 3600000);
+        const ageStr = days > 0 ? `${days}d ago` : `${hours}h ago`;
+        log.info(`  Orphaned: ${f.type}/${f.id} (${formatBytes(f.size || 0)}, cached ${ageStr})`);
+      }
+    }
+
+    // Evict only when storage exceeds threshold
+    if (report.storage.percent > this.threshold && orphaned.length > 0) {
+      log.warn(`Storage exceeds ${this.threshold}% threshold — evicting orphaned files`);
+      const targetBytes = storage.usage - (storage.quota * this.threshold / 100);
+      report.evicted = await this._evict(orphaned, targetBytes);
+    } else {
+      log.info(`No eviction needed (threshold: ${this.threshold}%)`);
+    }
+
+    return report;
+  }
+
+  /**
+   * Get storage estimate from the browser.
+   * Falls back to { usage: 0, quota: Infinity } in environments without the API.
+   */
+  async _getStorageEstimate() {
+    try {
+      if (typeof navigator !== 'undefined' && navigator.storage?.estimate) {
+        const { usage, quota } = await navigator.storage.estimate();
+        return { usage: usage || 0, quota: quota || Infinity };
+      }
+    } catch (e) {
+      log.warn('Storage estimate unavailable:', e.message);
+    }
+    return { usage: 0, quota: Infinity };
+  }
+
+  /**
+   * Evict orphaned files (oldest first) until targetBytes are freed.
+   *
+   * Deletes from both IndexedDB metadata and Cache API.
+   *
+   * @param {Array} orphanedFiles - Files to evict, sorted oldest-first
+   * @param {number} targetBytes - Bytes to free
+   * @returns {Promise<Array>} Evicted file records
+   */
+  async _evict(orphanedFiles, targetBytes) {
+    const evicted = [];
+    let freedBytes = 0;
+
+    for (const file of orphanedFiles) {
+      if (freedBytes >= targetBytes) break;
+
+      try {
+        // Delete from IndexedDB metadata
+        await this._deleteFileMetadata(file.id);
+
+        // Delete from Cache API
+        const cacheKey = this.cache.getCacheKey(file.type, file.id);
+        if (this.cache.cache) {
+          await this.cache.cache.delete(cacheKey);
+        }
+
+        freedBytes += file.size || 0;
+        evicted.push({
+          id: file.id,
+          type: file.type,
+          size: file.size || 0,
+          cachedAt: file.cachedAt || 0,
+        });
+
+        log.info(`  Evicted: ${file.type}/${file.id} (${formatBytes(file.size || 0)})`);
+      } catch (err) {
+        log.warn(`  Failed to evict ${file.type}/${file.id}:`, err.message);
+      }
+    }
+
+    log.info(`Evicted ${evicted.length} files, freed ${formatBytes(freedBytes)}`);
+    return evicted;
+  }
+
+  /**
+   * Delete a file record from IndexedDB.
+   */
+  async _deleteFileMetadata(id) {
+    return new Promise((resolve, reject) => {
+      const tx = this.cache.db.transaction('files', 'readwrite');
+      const store = tx.objectStore('files');
+      const request = store.delete(id);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+}
+
+export { formatBytes };

package/src/cache-analyzer.test.js

@@ -0,0 +1,291 @@
+/**
+ * CacheAnalyzer Tests
+ *
+ * Tests for stale media detection, storage health reporting, and eviction logic.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { CacheAnalyzer, formatBytes } from './cache-analyzer.js';
+
+describe('CacheAnalyzer', () => {
+  let analyzer;
+  let mockCache;
+
+  beforeEach(() => {
+    // Mock CacheManager with in-memory file store
+    const files = new Map();
+    const cacheStore = new Map();
+
+    mockCache = {
+      db: null, // Will be set up per-test if eviction is tested
+      cache: {
+        delete: vi.fn(async (key) => cacheStore.delete(key)),
+      },
+      getAllFiles: vi.fn(async () => [...files.values()]),
+      getCacheKey: vi.fn((type, id) => `/player/pwa/cache/${type}/${id}`),
+      // Helper to add test files
+      _files: files,
+      _addFile(record) {
+        files.set(record.id, record);
+      },
+    };
+
+    analyzer = new CacheAnalyzer(mockCache);
+  });
+
+  describe('formatBytes', () => {
+    it('should format bytes correctly', () => {
+      expect(formatBytes(0)).toBe('0 B');
+      expect(formatBytes(1024)).toBe('1.0 KB');
+      expect(formatBytes(1024 * 1024)).toBe('1.0 MB');
+      expect(formatBytes(1.5 * 1024 * 1024 * 1024)).toBe('1.5 GB');
+      expect(formatBytes(Infinity)).toBe('∞');
+    });
+  });
+
+  describe('analyze', () => {
+    it('should categorize required vs orphaned files', async () => {
+      mockCache._addFile({ id: '1', type: 'media', size: 1000, cachedAt: 100 });
+      mockCache._addFile({ id: '2', type: 'media', size: 2000, cachedAt: 200 });
+      mockCache._addFile({ id: '3', type: 'layout', size: 500, cachedAt: 300 });
+
+      const requiredFiles = [
+        { id: '1', type: 'media' },
+        { id: '3', type: 'layout' },
+      ];
+
+      const report = await analyzer.analyze(requiredFiles);
+
+      expect(report.files.required).toBe(2);
+      expect(report.files.orphaned).toBe(1);
+      expect(report.files.total).toBe(3);
+      expect(report.orphaned).toHaveLength(1);
+      expect(report.orphaned[0].id).toBe('2');
+      expect(report.orphanedSize).toBe(2000);
+    });
+
+    it('should report zero orphaned when all files are required', async () => {
+      mockCache._addFile({ id: '1', type: 'media', size: 1000, cachedAt: 100 });
+      mockCache._addFile({ id: '2', type: 'media', size: 2000, cachedAt: 200 });
+
+      const requiredFiles = [
+        { id: '1', type: 'media' },
+        { id: '2', type: 'media' },
+      ];
+
+      const report = await analyzer.analyze(requiredFiles);
+
+      expect(report.files.required).toBe(2);
+      expect(report.files.orphaned).toBe(0);
+      expect(report.orphaned).toHaveLength(0);
+      expect(report.orphanedSize).toBe(0);
+      expect(report.evicted).toHaveLength(0);
+    });
+
+    it('should handle empty cache', async () => {
+      const report = await analyzer.analyze([{ id: '1', type: 'media' }]);
+
+      expect(report.files.required).toBe(0);
+      expect(report.files.orphaned).toBe(0);
+      expect(report.files.total).toBe(0);
+    });
+
+    it('should handle empty required files list', async () => {
+      mockCache._addFile({ id: '1', type: 'media', size: 5000, cachedAt: 100 });
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.files.required).toBe(0);
+      expect(report.files.orphaned).toBe(1);
+      expect(report.orphanedSize).toBe(5000);
+    });
+
+    it('should sort orphaned files oldest first', async () => {
+      mockCache._addFile({ id: 'new', type: 'media', size: 100, cachedAt: 3000 });
+      mockCache._addFile({ id: 'old', type: 'media', size: 100, cachedAt: 1000 });
+      mockCache._addFile({ id: 'mid', type: 'media', size: 100, cachedAt: 2000 });
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.orphaned[0].id).toBe('old');
+      expect(report.orphaned[1].id).toBe('mid');
+      expect(report.orphaned[2].id).toBe('new');
+    });
+
+    it('should compare IDs as strings for mixed types', async () => {
+      mockCache._addFile({ id: '42', type: 'media', size: 100, cachedAt: 100 });
+
+      // RequiredFiles may use numeric IDs
+      const report = await analyzer.analyze([{ id: 42, type: 'media' }]);
+
+      expect(report.files.required).toBe(1);
+      expect(report.files.orphaned).toBe(0);
+    });
+
+    it('should not evict when storage is under threshold', async () => {
+      mockCache._addFile({ id: '1', type: 'media', size: 100, cachedAt: 100 });
+
+      // Mock storage at 50% (under default 80% threshold)
+      vi.stubGlobal('navigator', {
+        storage: {
+          estimate: vi.fn(async () => ({ usage: 500, quota: 1000 })),
+        },
+      });
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.storage.percent).toBe(50);
+      expect(report.evicted).toHaveLength(0);
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should include storage info in report', async () => {
+      vi.stubGlobal('navigator', {
+        storage: {
+          estimate: vi.fn(async () => ({ usage: 2_000_000_000, quota: 5_000_000_000 })),
+        },
+      });
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.storage.usage).toBe(2_000_000_000);
+      expect(report.storage.quota).toBe(5_000_000_000);
+      expect(report.storage.percent).toBe(40);
+      expect(report.threshold).toBe(80);
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should handle missing storage API gracefully', async () => {
+      // No navigator.storage
+      vi.stubGlobal('navigator', {});
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.storage.usage).toBe(0);
+      expect(report.storage.quota).toBe(Infinity);
+      expect(report.storage.percent).toBe(0);
+      expect(report.evicted).toHaveLength(0);
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should handle files with missing size or cachedAt', async () => {
+      mockCache._addFile({ id: '1', type: 'media' }); // no size, no cachedAt
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.files.orphaned).toBe(1);
+      expect(report.orphanedSize).toBe(0);
+      expect(report.orphaned[0].size).toBe(0);
+      expect(report.orphaned[0].cachedAt).toBe(0);
+    });
+  });
+
+  describe('eviction', () => {
+    let deletedIds;
+
+    beforeEach(() => {
+      deletedIds = [];
+
+      // Mock IndexedDB transaction for metadata deletion
+      const mockStore = {
+        delete: vi.fn((id) => {
+          deletedIds.push(id);
+          return { set onsuccess(fn) { fn(); }, set onerror(_) {} };
+        }),
+      };
+      mockCache.db = {
+        transaction: vi.fn(() => ({
+          objectStore: vi.fn(() => mockStore),
+        })),
+      };
+    });
+
+    it('should evict orphaned files when storage exceeds threshold', async () => {
+      mockCache._addFile({ id: 'old', type: 'media', size: 500, cachedAt: 1000 });
+      mockCache._addFile({ id: 'newer', type: 'media', size: 300, cachedAt: 2000 });
+      mockCache._addFile({ id: 'required', type: 'media', size: 1000, cachedAt: 500 });
+
+      // 90% usage — exceeds 80% threshold
+      vi.stubGlobal('navigator', {
+        storage: {
+          estimate: vi.fn(async () => ({ usage: 9000, quota: 10000 })),
+        },
+      });
+
+      const report = await analyzer.analyze([{ id: 'required', type: 'media' }]);
+
+      expect(report.evicted.length).toBeGreaterThan(0);
+      // Should evict oldest first
+      expect(report.evicted[0].id).toBe('old');
+      expect(deletedIds).toContain('old');
+      // Cache API delete should also be called
+      expect(mockCache.cache.delete).toHaveBeenCalled();
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should stop evicting once enough space is freed', async () => {
+      // 3 orphaned files, but only need to free a small amount
+      mockCache._addFile({ id: 'a', type: 'media', size: 2000, cachedAt: 1000 });
+      mockCache._addFile({ id: 'b', type: 'media', size: 2000, cachedAt: 2000 });
+      mockCache._addFile({ id: 'c', type: 'media', size: 2000, cachedAt: 3000 });
+
+      // 85% usage, threshold 80% → need to free 5% of 10000 = 500 bytes
+      // First file (2000 bytes) should be enough
+      vi.stubGlobal('navigator', {
+        storage: {
+          estimate: vi.fn(async () => ({ usage: 8500, quota: 10000 })),
+        },
+      });
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.evicted).toHaveLength(1);
+      expect(report.evicted[0].id).toBe('a'); // oldest
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should never evict required files', async () => {
+      mockCache._addFile({ id: 'keep', type: 'media', size: 5000, cachedAt: 100 });
+      mockCache._addFile({ id: 'orphan', type: 'media', size: 100, cachedAt: 200 });
+
+      vi.stubGlobal('navigator', {
+        storage: {
+          estimate: vi.fn(async () => ({ usage: 9500, quota: 10000 })),
+        },
+      });
+
+      const report = await analyzer.analyze([{ id: 'keep', type: 'media' }]);
+
+      // Only the orphan can be evicted, even though 'keep' is older and larger
+      const evictedIds = report.evicted.map(f => f.id);
+      expect(evictedIds).not.toContain('keep');
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should respect custom threshold', async () => {
+      analyzer = new CacheAnalyzer(mockCache, { threshold: 50 });
+
+      mockCache._addFile({ id: '1', type: 'media', size: 100, cachedAt: 100 });
+
+      // 60% usage — under 80% but over 50%
+      vi.stubGlobal('navigator', {
+        storage: {
+          estimate: vi.fn(async () => ({ usage: 6000, quota: 10000 })),
+        },
+      });
+
+      const report = await analyzer.analyze([]);
+
+      expect(report.threshold).toBe(50);
+      expect(report.evicted.length).toBeGreaterThan(0);
+
+      vi.unstubAllGlobals();
+    });
+  });
+});

package/src/cache.js

@@ -405,9 +405,9 @@ export class CacheManager {
     }
 
     // Rewrite absolute CMS signed URLs to local cache paths
-    // Matches: https://cms/xmds.php?file=bundle.min.js&...&X-Amz-Signature=...
+    // Matches: https://cms/xmds.php?file=... or https://cms/pwa/file?file=...
     // These absolute URLs bypass the <base> tag entirely, causing slow CMS fetches
-    const cmsUrlRegex = /https?:\/\/[^"'\s)]+xmds\.php\?[^"'\s)]*file=([^&"'\s)]+)[^"'\s)]*/g;
+    const cmsUrlRegex = /https?:\/\/[^"'\s)]+(?:xmds\.php|pwa\/file)\?[^"'\s)]*file=([^&"'\s)]+)[^"'\s)]*/g;
     const staticResources = [];
     modifiedHtml = modifiedHtml.replace(cmsUrlRegex, (match, filename) => {
       const localPath = `${BASE}/cache/static/${filename}`;

package/src/index.js

@@ -4,3 +4,4 @@ export const VERSION = pkg.version;
 export { CacheManager, cacheManager } from './cache.js';
 export { CacheProxy } from './cache-proxy.js';
 export { DownloadManager, FileDownload, LayoutTaskBuilder, isUrlExpired } from './download-manager.js';
+export { CacheAnalyzer } from './cache-analyzer.js';