@xiboplayer/sw 0.2.0 → 0.3.1

package/README.md

@@ -1,15 +1,16 @@
-# @xiboplayer/sw Documentation
+# @xiboplayer/sw
 
 **Service Worker toolkit for chunk streaming and offline caching.**
 
 ## Overview
 
-Provides Service Worker utilities for:
+Provides Service Worker building blocks for Xibo players:
 
-- **Chunk streaming** - Progressive media download
-- **Cache-first strategy** - Fast offline access
-- **Background sync** - Resilient updates
-- **Update mechanism** - Seamless SW updates
+- **Chunk streaming** — progressive download with Range request support for large media files
+- **BlobCache** — in-memory cache for assembled chunks with LRU eviction
+- **Widget HTML serving** — intercepts GetResource requests and serves from cache
+- **Version-aware activation** — prevents re-activation of same SW version to preserve in-flight streams
+- **XLF-driven media resolution** — parses layout XLF to determine exactly which media each layout needs
 
 ## Installation
 
@@ -17,47 +18,15 @@ Provides Service Worker utilities for:
 npm install @xiboplayer/sw
 ```
 
-## Usage
-
-```javascript
-// In main thread
-import { registerServiceWorker } from '@xiboplayer/sw';
-
-await registerServiceWorker('/sw.js');
-
-// In service worker
-import { setupChunkStreaming } from '@xiboplayer/sw/worker';
-
-self.addEventListener('install', event => {
-  event.waitUntil(setupChunkStreaming());
-});
-```
-
 ## Features
 
-- HTTP 206 Partial Content support
-- Automatic range request handling
-- Cache API integration
-- Update notifications
-
-## API Reference
-
-### registerServiceWorker(url)
-
-Registers Service Worker with update handling.
-
-### setupChunkStreaming()
-
-Configures SW for chunk-based streaming.
-
-## Dependencies
-
-None (zero dependencies)
-
-## Related Packages
+This package provides the core logic used by the PWA Service Worker (`sw-pwa.js`). The SW handles:
 
-- [@xiboplayer/cache](../../cache/docs/) - Cache management
+1. **Static caching** — PWA shell files cached on install
+2. **Media caching** — layout media downloaded via parallel chunks
+3. **Range requests** — video seeking served from cached chunks
+4. **Download queue** — flat queue with barriers for layout-ordered downloads
 
 ---
 
-**Package Version**: 1.0.0
+**Part of the [XiboPlayer SDK](https://github.com/xibo-players/xiboplayer)** | [MCP Server](https://github.com/xibo-players/xiboplayer/tree/main/mcp-server) for AI-assisted development

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@xiboplayer/sw",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Service Worker toolkit for chunk streaming and offline caching",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
-    "./worker": "./src/worker.js"
+    "./utils": "./src/sw-utils.js"
+  },
+  "dependencies": {
+    "@xiboplayer/cache": "0.3.1"
   },
-  "dependencies": {},
   "devDependencies": {
     "vitest": "^2.0.0"
   },

package/src/blob-cache.js

@@ -0,0 +1,111 @@
+/**
+ * BlobCache - LRU in-memory cache for blob objects
+ * Prevents re-materializing blobs from Cache API on every Range request
+ */
+
+import { formatBytes } from './sw-utils.js';
+import { SWLogger } from './chunk-config.js';
+
+export class BlobCache {
+  /**
+   * @param {number} [maxSizeMB=200] - Maximum cache size in megabytes
+   */
+  constructor(maxSizeMB = 200) {
+    this.cache = new Map(); // cacheKey → { blob, lastAccess, size }
+    this.maxBytes = maxSizeMB * 1024 * 1024;
+    this.currentBytes = 0;
+    this.log = new SWLogger('BlobCache');
+  }
+
+  /**
+   * Check if a key exists in memory cache (no Cache API fallback)
+   * @param {string} cacheKey - Cache key
+   * @returns {boolean}
+   */
+  has(cacheKey) {
+    return this.cache.has(cacheKey);
+  }
+
+  /**
+   * Get blob from cache or load via loader function
+   * @param {string} cacheKey - Cache key
+   * @param {Function} loader - Async function that returns blob
+   * @returns {Promise<Blob>}
+   */
+  async get(cacheKey, loader) {
+    // Check memory cache first
+    if (this.cache.has(cacheKey)) {
+      const entry = this.cache.get(cacheKey);
+      entry.lastAccess = Date.now();
+      this.log.debug(`HIT: ${cacheKey} (${formatBytes(entry.size)})`);
+      return entry.blob;
+    }
+
+    // Cache miss - load from Cache API
+    this.log.debug(`MISS: ${cacheKey} - loading from Cache API`);
+    const blob = await loader();
+
+    // Evict LRU entries if over limit
+    while (this.currentBytes + blob.size > this.maxBytes && this.cache.size > 0) {
+      this.evictLRU();
+    }
+
+    // Cache if under limit
+    if (this.currentBytes + blob.size <= this.maxBytes) {
+      this.cache.set(cacheKey, {
+        blob,
+        lastAccess: Date.now(),
+        size: blob.size
+      });
+      this.currentBytes += blob.size;
+      const utilization = (this.currentBytes / this.maxBytes * 100).toFixed(1);
+      this.log.debug(`CACHED: ${cacheKey} (${formatBytes(blob.size)}) - utilization: ${utilization}%`);
+    } else {
+      this.log.debug(`Skipping memory cache (too large): ${cacheKey} (${formatBytes(blob.size)} > ${formatBytes(this.maxBytes)})`);
+    }
+
+    return blob;
+  }
+
+  /**
+   * Evict least recently used entry
+   */
+  evictLRU() {
+    let oldest = null;
+    let oldestKey = null;
+
+    for (const [key, entry] of this.cache) {
+      if (!oldest || entry.lastAccess < oldest.lastAccess) {
+        oldest = entry;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      this.currentBytes -= oldest.size;
+      this.cache.delete(oldestKey);
+      this.log.debug(`EVICTED LRU: ${oldestKey} (${formatBytes(oldest.size)})`);
+    }
+  }
+
+  /**
+   * Clear all cached blobs
+   */
+  clear() {
+    this.cache.clear();
+    this.currentBytes = 0;
+    this.log.info('Cleared all cached blobs');
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats() {
+    return {
+      entries: this.cache.size,
+      bytes: this.currentBytes,
+      maxBytes: this.maxBytes,
+      utilization: (this.currentBytes / this.maxBytes * 100).toFixed(1) + '%'
+    };
+  }
+}

package/src/cache-manager.js

@@ -0,0 +1,270 @@
+/**
+ * CacheManager - Wraps Cache API with type-aware keys and chunk support
+ */
+
+import { formatBytes } from './sw-utils.js';
+import { SWLogger } from './chunk-config.js';
+
+export class CacheManager {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.cacheName='xibo-media-v1'] - Cache Storage name
+   * @param {number} [options.chunkSize] - Chunk size in bytes (required for putChunked)
+   */
+  constructor({ cacheName = 'xibo-media-v1', chunkSize } = {}) {
+    this.cache = null;
+    this.cacheName = cacheName;
+    this.chunkSize = chunkSize;
+    this.log = new SWLogger('Cache');
+
+    // In-memory metadata cache: cacheKey → metadata object
+    // Eliminates Cache API lookups for chunk metadata on every Range request
+    this.metadataCache = new Map();
+  }
+
+  async init() {
+    this.cache = await caches.open(this.cacheName);
+  }
+
+  /**
+   * Get cached file
+   * Returns Response or null
+   */
+  async get(cacheKey) {
+    if (!this.cache) await this.init();
+    // Use ignoreVary and ignoreSearch for more lenient matching
+    return await this.cache.match(cacheKey, {
+      ignoreSearch: true,
+      ignoreVary: true
+    });
+  }
+
+  /**
+   * Put file in cache
+   */
+  async put(cacheKey, blob, contentType) {
+    if (!this.cache) await this.init();
+
+    const response = new Response(blob, {
+      headers: {
+        'Content-Type': contentType,
+        'Content-Length': blob.size,
+        'Access-Control-Allow-Origin': '*',
+        'Accept-Ranges': 'bytes'
+      }
+    });
+
+    await this.cache.put(cacheKey, response);
+  }
+
+  /**
+   * Delete file from cache (whole file, or all chunks + metadata)
+   */
+  async delete(cacheKey) {
+    if (!this.cache) await this.init();
+
+    // Clear in-memory metadata cache
+    const meta = this.metadataCache.get(cacheKey);
+    this.metadataCache.delete(cacheKey);
+
+    // If chunked, delete all chunks + metadata
+    if (meta) {
+      const promises = [this.cache.delete(`${cacheKey}/metadata`)];
+      for (let i = 0; i < meta.numChunks; i++) {
+        promises.push(this.cache.delete(`${cacheKey}/chunk-${i}`));
+      }
+      await Promise.all(promises);
+      return true;
+    }
+
+    return await this.cache.delete(cacheKey);
+  }
+
+  /**
+   * Clear all cached files
+   */
+  async clear() {
+    if (!this.cache) await this.init();
+    const keys = await this.cache.keys();
+    await Promise.all(keys.map(key => this.cache.delete(key)));
+    this.metadataCache.clear();
+    this.log.info('Cleared', keys.length, 'cached files');
+  }
+
+  /**
+   * Check if file exists (supports both whole files and chunked storage)
+   * Single source of truth for file existence checks.
+   * Uses in-memory metadataCache to avoid Cache API lookups on hot paths.
+   * @param {string} cacheKey - Full cache key (e.g., /player/pwa/cache/media/6)
+   * @returns {Promise<{exists: boolean, chunked: boolean, metadata: Object|null}>}
+   */
+  async fileExists(cacheKey) {
+    if (!this.cache) await this.init();
+
+    // Fast path: check in-memory metadata cache first (no async I/O)
+    const cachedMeta = this.metadataCache.get(cacheKey);
+    if (cachedMeta) {
+      return { exists: true, chunked: true, metadata: cachedMeta };
+    }
+
+    // Check for whole file
+    const wholeFile = await this.get(cacheKey);
+    if (wholeFile) {
+      return { exists: true, chunked: false, metadata: null };
+    }
+
+    // Check for chunked metadata (Cache API fallback)
+    const metadata = await this.getMetadata(cacheKey);
+    if (metadata && metadata.chunked) {
+      // Populate in-memory cache for future requests
+      this.metadataCache.set(cacheKey, metadata);
+      return { exists: true, chunked: true, metadata };
+    }
+
+    return { exists: false, chunked: false, metadata: null };
+  }
+
+  /**
+   * Get file size (works for both whole files and chunks)
+   * @param {string} cacheKey - Full cache key
+   * @returns {Promise<number|null>} File size in bytes, or null if not found
+   */
+  async getFileSize(cacheKey) {
+    const info = await this.fileExists(cacheKey);
+
+    if (!info.exists) return null;
+
+    if (info.chunked) {
+      return info.metadata.totalSize;  // From chunked metadata
+    }
+
+    const response = await this.get(cacheKey);
+    const contentLength = response?.headers.get('Content-Length');
+    return contentLength ? parseInt(contentLength) : null;
+  }
+
+  /**
+   * Store file as chunks for large files (low memory streaming)
+   * @param {string} cacheKey - Base cache key (e.g., /player/pwa/cache/media/123)
+   * @param {Blob} blob - File blob to store as chunks
+   * @param {string} contentType - Content type
+   */
+  async putChunked(cacheKey, blob, contentType) {
+    if (!this.cache) await this.init();
+
+    const chunkSize = this.chunkSize;
+    const totalSize = blob.size;
+    const numChunks = Math.ceil(totalSize / chunkSize);
+
+    this.log.info(`Storing as ${numChunks} chunks: ${cacheKey} (${formatBytes(totalSize)})`);
+
+    // Store metadata (complete: false until all chunks are written)
+    const metadata = {
+      totalSize,
+      chunkSize,
+      numChunks,
+      contentType,
+      chunked: true,
+      complete: false,
+      createdAt: Date.now()
+    };
+
+    const metadataResponse = new Response(JSON.stringify(metadata), {
+      headers: { 'Content-Type': 'application/json' }
+    });
+    await this.cache.put(`${cacheKey}/metadata`, metadataResponse);
+    // Populate in-memory cache
+    this.metadataCache.set(cacheKey, metadata);
+
+    // Store chunks
+    for (let i = 0; i < numChunks; i++) {
+      const start = i * chunkSize;
+      const end = Math.min(start + chunkSize, totalSize);
+      const chunkBlob = blob.slice(start, end);
+
+      const chunkResponse = new Response(chunkBlob, {
+        headers: {
+          'Content-Type': contentType,
+          'Content-Length': chunkBlob.size,
+          'X-Chunk-Index': i,
+          'X-Total-Chunks': numChunks
+        }
+      });
+
+      await this.cache.put(`${cacheKey}/chunk-${i}`, chunkResponse);
+
+      if ((i + 1) % 5 === 0 || i === numChunks - 1) {
+        this.log.info(`Stored chunk ${i + 1}/${numChunks} (${formatBytes(chunkBlob.size)})`);
+      }
+    }
+
+    // All chunks stored — mark metadata complete
+    metadata.complete = true;
+    await this.cache.put(`${cacheKey}/metadata`, new Response(
+      JSON.stringify(metadata),
+      { headers: { 'Content-Type': 'application/json' } }
+    ));
+    this.metadataCache.set(cacheKey, metadata);
+
+    this.log.info(`Chunked storage complete: ${cacheKey}`);
+  }
+
+  /**
+   * Get metadata for chunked file.
+   * Checks in-memory cache first to avoid Cache API I/O on hot paths.
+   * @param {string} cacheKey - Base cache key
+   * @returns {Promise<Object|null>}
+   */
+  async getMetadata(cacheKey) {
+    // Fast path: in-memory cache
+    const cached = this.metadataCache.get(cacheKey);
+    if (cached) return cached;
+
+    if (!this.cache) await this.init();
+
+    const response = await this.cache.match(`${cacheKey}/metadata`);
+    if (!response) return null;
+
+    const text = await response.text();
+    const metadata = JSON.parse(text);
+
+    // Populate in-memory cache
+    this.metadataCache.set(cacheKey, metadata);
+    return metadata;
+  }
+
+  /**
+   * Update metadata both in Cache API and in-memory cache
+   * @param {string} cacheKey - Base cache key
+   * @param {Object} metadata - Metadata to store
+   */
+  async updateMetadata(cacheKey, metadata) {
+    if (!this.cache) await this.init();
+    await this.cache.put(`${cacheKey}/metadata`, new Response(
+      JSON.stringify(metadata),
+      { headers: { 'Content-Type': 'application/json' } }
+    ));
+    this.metadataCache.set(cacheKey, metadata);
+  }
+
+  /**
+   * Check if file is stored as chunks
+   * @param {string} cacheKey - Base cache key
+   * @returns {Promise<boolean>}
+   */
+  async isChunked(cacheKey) {
+    const metadata = await this.getMetadata(cacheKey);
+    return metadata?.chunked === true;
+  }
+
+  /**
+   * Get specific chunk
+   * @param {string} cacheKey - Base cache key
+   * @param {number} chunkIndex - Chunk index
+   * @returns {Promise<Response|null>}
+   */
+  async getChunk(cacheKey, chunkIndex) {
+    if (!this.cache) await this.init();
+    return await this.cache.match(`${cacheKey}/chunk-${chunkIndex}`);
+  }
+}

package/src/chunk-config.js

@@ -0,0 +1,111 @@
+/**
+ * Service Worker logger and chunk configuration
+ */
+
+/**
+ * Simple logger for Service Worker context.
+ * Uses console but can be configured via self.swLogLevel.
+ */
+export class SWLogger {
+  constructor(name) {
+    this.name = name;
+    // Default level: INFO (can be changed via self.swLogLevel = 'DEBUG')
+    this.level = (typeof self !== 'undefined' && self.swLogLevel) || 'INFO';
+  }
+
+  debug(...args) {
+    if (this.level === 'DEBUG') {
+      console.log(`[${this.name}] DEBUG:`, ...args);
+    }
+  }
+
+  info(...args) {
+    if (this.level === 'DEBUG' || this.level === 'INFO') {
+      console.log(`[${this.name}]`, ...args);
+    }
+  }
+
+  warn(...args) {
+    console.warn(`[${this.name}]`, ...args);
+  }
+
+  error(...args) {
+    console.error(`[${this.name}]`, ...args);
+  }
+}
+
+/**
+ * Calculate optimal chunk size based on available device memory.
+ * Returns configuration for chunk streaming, blob caching, and download concurrency.
+ *
+ * @param {{ info: Function }} [log] - Optional logger (created internally if not provided)
+ * @returns {{ chunkSize: number, blobCacheSize: number, threshold: number, concurrency: number }}
+ */
+export function calculateChunkConfig(log) {
+  if (!log) log = new SWLogger('ChunkConfig');
+
+  // Try to detect device memory (Chrome only for now)
+  const deviceMemoryGB = (typeof navigator !== 'undefined' && navigator.deviceMemory) || null;
+
+  // Fallback: estimate from user agent
+  let estimatedRAM_GB = 4; // Default assumption
+
+  if (deviceMemoryGB) {
+    estimatedRAM_GB = deviceMemoryGB;
+    log.info('Detected device memory:', deviceMemoryGB, 'GB');
+  } else if (typeof navigator !== 'undefined') {
+    // Parse user agent for hints
+    const ua = navigator.userAgent.toLowerCase();
+    if (ua.includes('raspberry pi') || ua.includes('armv6')) {
+      estimatedRAM_GB = 0.5; // Pi Zero
+      log.info('Detected Pi Zero (512 MB RAM estimated)');
+    } else if (ua.includes('armv7')) {
+      estimatedRAM_GB = 1; // Pi 3/4
+      log.info('Detected ARM device (1 GB RAM estimated)');
+    } else {
+      log.info('Using default RAM estimate:', estimatedRAM_GB, 'GB');
+    }
+  }
+
+  // Configure based on RAM - chunk size, cache, threshold, AND concurrency
+  let chunkSize, blobCacheSize, threshold, concurrency;
+
+  if (estimatedRAM_GB <= 0.5) {
+    // Pi Zero (512 MB) - very conservative
+    chunkSize = 10 * 1024 * 1024;
+    blobCacheSize = 25;
+    threshold = 25 * 1024 * 1024;
+    concurrency = 1;
+    log.info('Low-memory config: 10 MB chunks, 25 MB cache, 1 concurrent download');
+  } else if (estimatedRAM_GB <= 1) {
+    // 1 GB RAM (Pi 3) - conservative
+    chunkSize = 20 * 1024 * 1024;
+    blobCacheSize = 50;
+    threshold = 50 * 1024 * 1024;
+    concurrency = 2;
+    log.info('1GB-RAM config: 20 MB chunks, 50 MB cache, 2 concurrent downloads');
+  } else if (estimatedRAM_GB <= 2) {
+    // 2 GB RAM - moderate
+    chunkSize = 30 * 1024 * 1024;
+    blobCacheSize = 100;
+    threshold = 75 * 1024 * 1024;
+    concurrency = 2;
+    log.info('2GB-RAM config: 30 MB chunks, 100 MB cache, 2 concurrent downloads');
+  } else if (estimatedRAM_GB <= 4) {
+    // 4 GB RAM - default
+    chunkSize = 50 * 1024 * 1024;
+    blobCacheSize = 200;
+    threshold = 100 * 1024 * 1024;
+    concurrency = 4;
+    log.info('4GB-RAM config: 50 MB chunks, 200 MB cache, 4 concurrent downloads');
+  } else {
+    // 8+ GB RAM - generous
+    chunkSize = 100 * 1024 * 1024;
+    blobCacheSize = 500;
+    threshold = 200 * 1024 * 1024;
+    concurrency = 6;
+    log.info('High-RAM config: 100 MB chunks, 500 MB cache, 6 concurrent downloads');
+  }
+
+  return { chunkSize, blobCacheSize, threshold, concurrency };
+}

package/src/index.js

@@ -1,23 +1,7 @@
-// @xiboplayer/sw - Service Worker toolkit
-export async function registerServiceWorker(swUrl, options = {}) {
-  if (!('serviceWorker' in navigator)) {
-    console.warn('Service Workers not supported');
-    return null;
-  }
-
-  try {
-    const registration = await navigator.serviceWorker.register(swUrl, options);
-    console.log('Service Worker registered:', registration);
-    return registration;
-  } catch (error) {
-    console.error('Service Worker registration failed:', error);
-    throw error;
-  }
-}
-
-export async function unregisterServiceWorker() {
-  if (!('serviceWorker' in navigator)) return false;
-
-  const registration = await navigator.serviceWorker.ready;
-  return await registration.unregister();
-}
+// @xiboplayer/sw - Service Worker toolkit for chunk streaming and offline caching
+export { CacheManager } from './cache-manager.js';
+export { BlobCache } from './blob-cache.js';
+export { RequestHandler } from './request-handler.js';
+export { MessageHandler } from './message-handler.js';
+export { extractMediaIdsFromXlf } from './xlf-parser.js';
+export { calculateChunkConfig, SWLogger } from './chunk-config.js';