Add cache size and entry limiting options

rosa · claude · rosa · commit cff29da0f7a5 · 2026-02-05T10:21:58.000+01:00
Add three new cache limiting options to offline handlers:
- maxSize: total cache size limit in bytes (trims oldest when exceeded)
- maxEntrySize: rejects individual entries over this size before caching
- maxEntries: total number of entries (trims oldest when exceeded)

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/src/offline/cache_registry.js b/src/offline/cache_registry.js
@@ -54,6 +54,60 @@ class CacheRegistryDatabase {
     return this.#performOperation(STORE_NAME, getOlderThanOp, "readonly")
   }
 
+  getEntryCount(cacheName) {
+    const countOp = (store) => {
+      const index = store.index("cacheNameAndTimestamp")
+      const range = IDBKeyRange.bound(
+        [cacheName, 0],
+        [cacheName, Infinity]
+      )
+      return this.#requestToPromise(index.count(range))
+    }
+    return this.#performOperation(STORE_NAME, countOp, "readonly")
+  }
+
+  getTotalSize(cacheName) {
+    const sumOp = (store) => {
+      const index = store.index("cacheNameAndTimestamp")
+      const range = IDBKeyRange.bound(
+        [cacheName, 0],
+        [cacheName, Infinity]
+      )
+      const cursorRequest = index.openCursor(range)
+
+      return this.#sumSizesFromCursor(cursorRequest)
+    }
+    return this.#performOperation(STORE_NAME, sumOp, "readonly")
+  }
+
+  getOldestEntries(cacheName, limit) {
+    const getOldestOp = (store) => {
+      const index = store.index("cacheNameAndTimestamp")
+      const range = IDBKeyRange.bound(
+        [cacheName, 0],
+        [cacheName, Infinity]
+      )
+      const cursorRequest = index.openCursor(range)
+
+      return this.#cursorRequestToPromiseWithLimit(cursorRequest, limit)
+    }
+    return this.#performOperation(STORE_NAME, getOldestOp, "readonly")
+  }
+
+  getEntriesForSizeReduction(cacheName, targetReduction) {
+    const getEntriesOp = (store) => {
+      const index = store.index("cacheNameAndTimestamp")
+      const range = IDBKeyRange.bound(
+        [cacheName, 0],
+        [cacheName, Infinity]
+      )
+      const cursorRequest = index.openCursor(range)
+
+      return this.#getEntriesUntilSizeReached(cursorRequest, targetReduction)
+    }
+    return this.#performOperation(STORE_NAME, getEntriesOp, "readonly")
+  }
+
   delete(key) {
     const deleteOp = (store) => this.#requestToPromise(store.delete(key))
     return this.#performOperation(STORE_NAME, deleteOp, "readwrite")
@@ -101,6 +155,62 @@ class CacheRegistryDatabase {
       request.onerror = () => reject(request.error)
     })
   }
+
+  #cursorRequestToPromiseWithLimit(request, limit) {
+    return new Promise((resolve, reject) => {
+      const results = []
+
+      request.onsuccess = (event) => {
+        const cursor = event.target.result
+        if (cursor && results.length < limit) {
+          results.push(cursor.value)
+          cursor.continue()
+        } else {
+          resolve(results)
+        }
+      }
+
+      request.onerror = () => reject(request.error)
+    })
+  }
+
+  #sumSizesFromCursor(request) {
+    return new Promise((resolve, reject) => {
+      let total = 0
+
+      request.onsuccess = (event) => {
+        const cursor = event.target.result
+        if (cursor) {
+          total += cursor.value.size ?? 0
+          cursor.continue()
+        } else {
+          resolve(total)
+        }
+      }
+
+      request.onerror = () => reject(request.error)
+    })
+  }
+
+  #getEntriesUntilSizeReached(request, targetSize) {
+    return new Promise((resolve, reject) => {
+      const results = []
+      let accumulated = 0
+
+      request.onsuccess = (event) => {
+        const cursor = event.target.result
+        if (cursor && accumulated < targetSize) {
+          results.push(cursor.value)
+          accumulated += cursor.value.size ?? 0
+          cursor.continue()
+        } else {
+          resolve(results)
+        }
+      }
+
+      request.onerror = () => reject(request.error)
+    })
+  }
 }
 
 let cacheRegistryDatabase = null
@@ -138,6 +248,22 @@ export class CacheRegistry {
     return this.database.getOlderThan(this.cacheName, timestamp)
   }
 
+  getEntryCount() {
+    return this.database.getEntryCount(this.cacheName)
+  }
+
+  getTotalSize() {
+    return this.database.getTotalSize(this.cacheName)
+  }
+
+  getOldestEntries(limit) {
+    return this.database.getOldestEntries(this.cacheName, limit)
+  }
+
+  getEntriesForSizeReduction(targetReduction) {
+    return this.database.getEntriesForSizeReduction(this.cacheName, targetReduction)
+  }
+
   delete(key) {
     return this.database.delete(key)
   }
diff --git a/src/offline/cache_trimmer.js b/src/offline/cache_trimmer.js
@@ -26,15 +26,23 @@ export class CacheTrimmer {
   }
 
   #shouldTrim() {
-    // For now, only check maxAge. To be extended for maxEntries, maxStorage, etc.
-    return this.options.maxAge && this.options.maxAge > 0
+    const { maxAge, maxEntries, maxSize } = this.options
+    return (maxAge && maxAge > 0) ||
+           (maxEntries && maxEntries > 0) ||
+           (maxSize && maxSize > 0)
   }
 
   async deleteEntries() {
+    // Order: age first → count → size (each reduces the set for subsequent operations)
     if (this.options.maxAge) {
       await this.deleteEntriesByAge()
     }
-    // To be extended with other options
+    if (this.options.maxEntries) {
+      await this.deleteEntriesByCount()
+    }
+    if (this.options.maxSize) {
+      await this.deleteEntriesBySize()
+    }
   }
 
   async deleteEntriesByAge() {
@@ -48,18 +56,58 @@ export class CacheTrimmer {
     }
 
     console.debug(`Trimming ${expiredEntries.length} expired entries from cache "${this.cacheName}"`)
+    await this.#deleteEntryList(expiredEntries)
+    console.debug(`Successfully trimmed ${expiredEntries.length} entries from cache "${this.cacheName}"`)
+  }
+
+  async deleteEntriesByCount() {
+    const currentCount = await this.cacheRegistry.getEntryCount()
+    const excess = currentCount - this.options.maxEntries
+
+    if (excess <= 0) {
+      return
+    }
+
+    const entriesToDelete = await this.cacheRegistry.getOldestEntries(excess)
+
+    if (entriesToDelete.length === 0) {
+      return
+    }
+
+    console.debug(`Trimming ${entriesToDelete.length} entries (count limit) from cache "${this.cacheName}"`)
+    await this.#deleteEntryList(entriesToDelete)
+    console.debug(`Successfully trimmed ${entriesToDelete.length} entries from cache "${this.cacheName}"`)
+  }
+
+  async deleteEntriesBySize() {
+    const currentSize = await this.cacheRegistry.getTotalSize()
+    const excess = currentSize - this.options.maxSize
 
+    if (excess <= 0) {
+      return
+    }
+
+    const entriesToDelete = await this.cacheRegistry.getEntriesForSizeReduction(excess)
+
+    if (entriesToDelete.length === 0) {
+      return
+    }
+
+    console.debug(`Trimming ${entriesToDelete.length} entries (size limit) from cache "${this.cacheName}"`)
+    await this.#deleteEntryList(entriesToDelete)
+    console.debug(`Successfully trimmed ${entriesToDelete.length} entries from cache "${this.cacheName}"`)
+  }
+
+  async #deleteEntryList(entries) {
     const cache = await caches.open(this.cacheName)
 
-    const deletePromises = expiredEntries.map(async (entry) => {
+    const deletePromises = entries.map(async (entry) => {
       const cacheDeletePromise = cache.delete(entry.key)
       const registryDeletePromise = this.cacheRegistry.delete(entry.key)
 
       return Promise.all([cacheDeletePromise, registryDeletePromise])
     })
 
     await Promise.all(deletePromises)
-
-    console.debug(`Successfully trimmed ${expiredEntries.length} entries from cache "${this.cacheName}"`)
   }
 }
diff --git a/src/offline/handlers/handler.js b/src/offline/handlers/handler.js
@@ -3,13 +3,14 @@ import { CacheTrimmer } from "../cache_trimmer"
 import { buildPartialResponse } from "../range_request"
 
 export class Handler {
-  constructor({ cacheName, networkTimeout, maxAge, fetchOptions }) {
+  constructor({ cacheName, networkTimeout, maxAge, maxEntries, maxSize, maxEntrySize, fetchOptions }) {
     this.cacheName = cacheName
     this.networkTimeout = networkTimeout
     this.fetchOptions = fetchOptions || {}
+    this.maxEntrySize = maxEntrySize
 
     this.cacheRegistry = new CacheRegistry(cacheName)
-    this.cacheTrimmer = new CacheTrimmer(cacheName, this.cacheRegistry, { maxAge })
+    this.cacheTrimmer = new CacheTrimmer(cacheName, this.cacheRegistry, { maxAge, maxEntries, maxSize })
   }
 
   async handle(request) {
@@ -45,11 +46,22 @@ export class Handler {
 
   async saveToCache(request, response) {
     if (response && this.canCacheResponse(response)) {
+      const size = await this.#getResponseSize(response)
+
+      if (this.maxEntrySize && this.maxEntrySize > 0) {
+        if (size === null) {
+          console.warn(`Cannot determine size for opaque response to "${request.url}". maxEntrySize check skipped.`)
+        } else if (size > this.maxEntrySize) {
+          console.debug(`Skipping cache for "${request.url}": response size ${size} exceeds maxEntrySize ${this.maxEntrySize}`)
+          return
+        }
+      }
+
       const cacheKeyUrl = buildCacheKey(request, response)
       const cache = await caches.open(this.cacheName)
 
       const cachePromise = cache.put(cacheKeyUrl, response)
-      const registryPromise = this.cacheRegistry.put(cacheKeyUrl)
+      const registryPromise = this.cacheRegistry.put(cacheKeyUrl, { size })
       const trimPromise = this.cacheTrimmer.trim()
 
       return Promise.all([ cachePromise, registryPromise, trimPromise ]).catch(async (error) => {
@@ -61,6 +73,21 @@ export class Handler {
     }
   }
 
+  async #getResponseSize(response) {
+    if (response.type === "opaque" || response.status === 0) {
+      return null
+    }
+
+    const contentLength = response.headers.get("Content-Length")
+    if (contentLength) {
+      return parseInt(contentLength, 10)
+    }
+
+    const clone = response.clone()
+    const blob = await clone.blob()
+    return blob.size
+  }
+
   canCacheResponse(response) {
     // OK response and opaque responses (due to CORS), that have a 0 status
     return response.status === 200 || response.status === 0
diff --git a/src/tests/fixtures/service_workers/max_entries.js b/src/tests/fixtures/service_workers/max_entries.js
@@ -0,0 +1,19 @@
+// Registered as type="classic", can't use module imports
+importScripts("/dist/turbo-offline-umd.js")
+
+// Cache-first handler with maxEntries limit for testing entry count trimming
+TurboOffline.addRule({
+  match: /\/dynamic\.txt/,
+  handler: TurboOffline.handlers.cacheFirst({
+    cacheName: "test-max-entries",
+    maxEntries: 3
+  })
+})
+
+// Take control of all pages immediately when activated
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim())
+})
+
+// Start the service worker
+TurboOffline.start()
diff --git a/src/tests/fixtures/service_workers/max_entry_size.js b/src/tests/fixtures/service_workers/max_entry_size.js
@@ -0,0 +1,29 @@
+// Registered as type="classic", can't use module imports
+importScripts("/dist/turbo-offline-umd.js")
+
+// Cache-first handler with maxEntrySize limit for testing individual entry size rejection
+// The dynamic.txt responses are ~60-70 bytes, so 50 bytes should reject them
+TurboOffline.addRule({
+  match: /\/dynamic\.txt/,
+  handler: TurboOffline.handlers.cacheFirst({
+    cacheName: "test-max-entry-size",
+    maxEntrySize: 50
+  })
+})
+
+// Handler with larger maxEntrySize that should allow caching
+TurboOffline.addRule({
+  match: /\/dynamic\.json$/,
+  handler: TurboOffline.handlers.cacheFirst({
+    cacheName: "test-max-entry-size-allowed",
+    maxEntrySize: 500
+  })
+})
+
+// Take control of all pages immediately when activated
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim())
+})
+
+// Start the service worker
+TurboOffline.start()
diff --git a/src/tests/fixtures/service_workers/max_size.js b/src/tests/fixtures/service_workers/max_size.js
@@ -0,0 +1,20 @@
+// Registered as type="classic", can't use module imports
+importScripts("/dist/turbo-offline-umd.js")
+
+// Cache-first handler with maxSize limit for testing total size trimming
+// The dynamic.txt responses are ~60-70 bytes each, so 150 bytes allows ~2 entries
+TurboOffline.addRule({
+  match: /\/dynamic\.txt/,
+  handler: TurboOffline.handlers.cacheFirst({
+    cacheName: "test-max-size",
+    maxSize: 150
+  })
+})
+
+// Take control of all pages immediately when activated
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim())
+})
+
+// Start the service worker
+TurboOffline.start()
diff --git a/src/tests/functional/offline_tests.js b/src/tests/functional/offline_tests.js
