@xiboplayer/cache 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/cache",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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.4"
+    "@xiboplayer/utils": "0.3.6"
   },
   "devDependencies": {
     "vitest": "^2.0.0",

package/src/cache-analyzer.js

@@ -0,0 +1,176 @@
+/**
+ * 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.
+ *
+ * Works entirely through CacheProxy (postMessage to SW) — no IndexedDB,
+ * no direct Cache API access.
+ */
+
+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-proxy.js').CacheProxy} cache - CacheProxy 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.
+   * Delegates deletion to CacheProxy.deleteFiles() which routes to SW.
+   *
+   * @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 toEvict = [];
+    let plannedBytes = 0;
+
+    for (const file of orphanedFiles) {
+      if (plannedBytes >= targetBytes) break;
+      toEvict.push(file);
+      plannedBytes += file.size || 0;
+    }
+
+    if (toEvict.length === 0) return [];
+
+    try {
+      const filesToDelete = toEvict.map(f => ({ type: f.type, id: f.id }));
+      await this.cache.deleteFiles(filesToDelete);
+
+      for (const f of toEvict) {
+        log.info(`  Evicted: ${f.type}/${f.id} (${formatBytes(f.size || 0)})`);
+      }
+      log.info(`Evicted ${toEvict.length} files, freed ${formatBytes(plannedBytes)}`);
+    } catch (err) {
+      log.warn('Eviction failed:', err.message);
+      return [];
+    }
+
+    return toEvict.map(f => ({
+      id: f.id,
+      type: f.type,
+      size: f.size || 0,
+      cachedAt: f.cachedAt || 0,
+    }));
+  }
+}
+
+export { formatBytes };

package/src/cache-analyzer.test.js

@@ -0,0 +1,270 @@
+/**
+ * CacheAnalyzer Tests
+ *
+ * Tests for stale media detection, storage health reporting, and eviction logic.
+ * Mock follows the CacheProxy interface (getAllFiles, deleteFiles).
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { CacheAnalyzer, formatBytes } from './cache-analyzer.js';
+
+describe('CacheAnalyzer', () => {
+  let analyzer;
+  let mockCache;
+
+  beforeEach(() => {
+    // Mock CacheProxy with in-memory file store
+    const files = new Map();
+
+    mockCache = {
+      getAllFiles: vi.fn(async () => [...files.values()]),
+      deleteFiles: vi.fn(async (filesToDelete) => ({
+        deleted: filesToDelete.length,
+        total: filesToDelete.length,
+      })),
+      // 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', () => {
+    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');
+      // deleteFiles should be called on the cache proxy
+      expect(mockCache.deleteFiles).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-proxy.js

@@ -416,6 +416,32 @@ export class CacheProxy extends EventEmitter {
     return this.backendType === 'service-worker';
   }
 
+  /**
+   * Get all cached files from Service Worker
+   * @returns {Promise<Array<{id: string, type: string, size: number, cachedAt: number}>>}
+   */
+  async getAllFiles() {
+    if (!this.backend) {
+      throw new Error('CacheProxy not initialized');
+    }
+
+    return new Promise((resolve) => {
+      const channel = new MessageChannel();
+
+      channel.port1.onmessage = (event) => {
+        const { success, files } = event.data;
+        resolve(success ? files : []);
+      };
+
+      navigator.serviceWorker.controller.postMessage(
+        { type: 'GET_ALL_FILES' },
+        [channel.port2]
+      );
+
+      setTimeout(() => resolve([]), 5000);
+    });
+  }
+
   /**
    * Delete files from cache (purge obsolete media)
    * @param {Array<{type: string, id: string}>} files - Files to delete