chore (change-history):

- harden localStorage writes and snapshot retention
- catch quota/private-mode failures on setItem
- cap full-spec snapshots by size (512KB) and TTL (30 days) so history data cannot
grow or linger unbounded.

Author: tunjiadeyemi

src/core/config/defaults.js

@@ -19,6 +19,10 @@ const defaultOptions = Object.freeze({
   persistAuthorization: false,
   changeHistory: true,
   changeHistoryMaxEntries: 20,
+  // --- soft cap for the full-spec snapshot persisted to localStorage (UTF-8 bytes)
+  changeHistoryMaxSnapshotBytes: 512 * 1024,
+  // --- drop change-history data older than this (30 days)
+  changeHistoryTtlMs: 30 * 24 * 60 * 60 * 1000,
   configs: {},
   displayOperationId: false,
   displayRequestDuration: false,

src/core/plugins/change-history/fn.js

@@ -603,3 +603,102 @@ export function formatChangeSummary(change) {
 export const STORAGE_PREFIX = "swagger-ui-change-history"
 export const SNAPSHOT_PREFIX = "swagger-ui-change-snapshot"
 export const VIEWED_PREFIX = "swagger-ui-change-history-viewed"
+
+/** Soft cap for a single persisted snapshot (UTF-8 bytes). */
+export const DEFAULT_MAX_SNAPSHOT_BYTES = 512 * 1024
+
+/** Drop history/snapshots older than this (30 days). */
+export const DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000
+
+export function getSerializedByteLength(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value)
+  if (typeof TextEncoder !== "undefined") {
+    return new TextEncoder().encode(text).length
+  }
+  return text.length
+}
+
+export function wrapSnapshot(spec, savedAt = Date.now()) {
+  return { savedAt, spec }
+}
+
+export function wrapOversizedSnapshotMarker(specHash, savedAt = Date.now()) {
+  return { savedAt, oversized: true, specHash }
+}
+
+export function unwrapSnapshot(value, { ttlMs, now = Date.now() } = {}) {
+  if (!value || typeof value !== "object") {
+    return null
+  }
+
+  // Oversized markers intentionally omit the full spec
+  if (value.oversized) {
+    return null
+  }
+
+  const isWrapped =
+    Object.prototype.hasOwnProperty.call(value, "spec") &&
+    Object.prototype.hasOwnProperty.call(value, "savedAt")
+
+  const spec = isWrapped ? value.spec : value
+  const savedAt = isWrapped ? value.savedAt : null
+
+  if (!spec || typeof spec !== "object") {
+    return null
+  }
+
+  if (
+    savedAt != null &&
+    ttlMs != null &&
+    ttlMs > 0 &&
+    now - savedAt > ttlMs
+  ) {
+    return null
+  }
+
+  return { spec, savedAt }
+}
+
+export function isOversizedSnapshotMarker(value, { ttlMs, now = Date.now() } = {}) {
+  if (!value || typeof value !== "object" || !value.oversized) {
+    return false
+  }
+
+  if (
+    value.savedAt != null &&
+    ttlMs != null &&
+    ttlMs > 0 &&
+    now - value.savedAt > ttlMs
+  ) {
+    return false
+  }
+
+  return true
+}
+
+export function filterHistoryByTtl(history, ttlMs, now = Date.now()) {
+  if (!Array.isArray(history)) {
+    return []
+  }
+
+  if (!ttlMs || ttlMs <= 0) {
+    return history
+  }
+
+  return history.filter(
+    (entry) =>
+      entry &&
+      typeof entry.timestamp === "number" &&
+      now - entry.timestamp <= ttlMs
+  )
+}
+
+export function canPersistSnapshot(spec, maxBytes, savedAt = Date.now()) {
+  if (!maxBytes || maxBytes <= 0) {
+    return true
+  }
+
+  return (
+    getSerializedByteLength(wrapSnapshot(spec, savedAt)) <= maxBytes
+  )
+}

src/core/plugins/change-history/spec-actions.js

@@ -1,10 +1,18 @@
 import {
+  canPersistSnapshot,
   compareSpecs,
+  DEFAULT_MAX_SNAPSHOT_BYTES,
+  DEFAULT_TTL_MS,
+  filterHistoryByTtl,
   getStorageKey,
   hashSpec,
+  isOversizedSnapshotMarker,
   SNAPSHOT_PREFIX,
   STORAGE_PREFIX,
+  unwrapSnapshot,
   VIEWED_PREFIX,
+  wrapOversizedSnapshotMarker,
+  wrapSnapshot,
 } from "./fn"
 
 function readJson(key, fallback) {
@@ -17,7 +25,27 @@ function readJson(key, fallback) {
 }
 
 function writeJson(key, value) {
-  localStorage.setItem(key, JSON.stringify(value))
+  try {
+    localStorage.setItem(key, JSON.stringify(value))
+    return true
+  } catch (err) {
+    console.warn(
+      "Swagger UI: unable to persist change history to localStorage",
+      err
+    )
+    return false
+  }
+}
+
+function removeKey(key) {
+  try {
+    localStorage.removeItem(key)
+  } catch (err) {
+    console.warn(
+      "Swagger UI: unable to remove change history from localStorage",
+      err
+    )
+  }
 }
 
 function getHistoryStorageKey(storageKey) {
@@ -32,6 +60,12 @@ function getViewedStorageKey(storageKey) {
   return `${VIEWED_PREFIX}:${storageKey}`
 }
 
+function clearPersistedHistory(storageKey) {
+  removeKey(getHistoryStorageKey(storageKey))
+  removeKey(getSnapshotStorageKey(storageKey))
+  removeKey(getViewedStorageKey(storageKey))
+}
+
 export const recordSpecLoad = () => (system) => {
   const {
     specSelectors,
@@ -54,22 +88,51 @@ export const recordSpecLoad = () => (system) => {
   const storageKey = getStorageKey(url, spec)
   const specHash = hashSpec(spec)
   const maxEntries = configs.changeHistoryMaxEntries || 20
+  const maxSnapshotBytes =
+    configs.changeHistoryMaxSnapshotBytes ?? DEFAULT_MAX_SNAPSHOT_BYTES
+  const ttlMs = configs.changeHistoryTtlMs ?? DEFAULT_TTL_MS
+  const now = Date.now()
 
   changeHistoryActions.setStorageKey(storageKey)
 
   const historyKey = getHistoryStorageKey(storageKey)
   const snapshotKey = getSnapshotStorageKey(storageKey)
   const viewedKey = getViewedStorageKey(storageKey)
 
-  const existingHistory = readJson(historyKey, [])
-  const previousSnapshot = readJson(snapshotKey, null)
+  const existingHistory = filterHistoryByTtl(
+    readJson(historyKey, []),
+    ttlMs,
+    now
+  )
+  const rawSnapshot = readJson(snapshotKey, null)
+  const previousSnapshotPayload = unwrapSnapshot(rawSnapshot, {
+    ttlMs,
+    now,
+  })
+  const previousSnapshot = previousSnapshotPayload
+    ? previousSnapshotPayload.spec
+    : null
   const lastViewedAt = readJson(viewedKey, 0)
+  const oversizedMarker = isOversizedSnapshotMarker(rawSnapshot, {
+    ttlMs,
+    now,
+  })
+
+  // Drop expired / invalid snapshot payloads from disk
+  if (rawSnapshot && !previousSnapshotPayload && !oversizedMarker) {
+    removeKey(snapshotKey)
+  }
 
-  if (previousSnapshot && hashSpec(previousSnapshot) === specHash) {
+  if (
+    (previousSnapshot && hashSpec(previousSnapshot) === specHash) ||
+    (oversizedMarker && rawSnapshot.specHash === specHash)
+  ) {
     changeHistoryActions.setHistory(existingHistory)
     changeHistoryActions.setUnseenChanges(
       existingHistory.some((entry) => entry.timestamp > lastViewedAt)
     )
+    // Keep history pruned on disk even when the snapshot is unchanged
+    writeJson(historyKey, existingHistory)
     return
   }
 
@@ -81,8 +144,8 @@ export const recordSpecLoad = () => (system) => {
 
   if (!previousSnapshot || changes.length) {
     const entry = {
-      id: `${Date.now()}`,
-      timestamp: Date.now(),
+      id: `${now}`,
+      timestamp: now,
       version: spec?.info?.version || null,
       title: spec?.info?.title || null,
       specHash,
@@ -92,7 +155,16 @@ export const recordSpecLoad = () => (system) => {
 
     const nextHistory = [entry, ...existingHistory].slice(0, maxEntries)
     writeJson(historyKey, nextHistory)
-    writeJson(snapshotKey, spec)
+
+    if (canPersistSnapshot(spec, maxSnapshotBytes, now)) {
+      writeJson(snapshotKey, wrapSnapshot(spec, now))
+    } else {
+      console.warn(
+        "Swagger UI: change-history snapshot exceeds size limit; skipping localStorage snapshot persistence"
+      )
+      // Keep a tiny marker so we do not re-baseline on every reload
+      writeJson(snapshotKey, wrapOversizedSnapshotMarker(specHash, now))
+    }
 
     changeHistoryActions.setHistory(nextHistory)
 
@@ -102,6 +174,7 @@ export const recordSpecLoad = () => (system) => {
     }
   } else {
     changeHistoryActions.setHistory(existingHistory)
+    writeJson(historyKey, existingHistory)
   }
 }
 
@@ -118,10 +191,29 @@ export const restoreHistory = () => (system) => {
     return
   }
 
+  const ttlMs = configs.changeHistoryTtlMs ?? DEFAULT_TTL_MS
+  const now = Date.now()
   const historyKey = getHistoryStorageKey(storageKey)
+  const snapshotKey = getSnapshotStorageKey(storageKey)
   const viewedKey = getViewedStorageKey(storageKey)
-  const existingHistory = readJson(historyKey, [])
+  const existingHistory = filterHistoryByTtl(
+    readJson(historyKey, []),
+    ttlMs,
+    now
+  )
   const lastViewedAt = readJson(viewedKey, 0)
+  const rawSnapshot = readJson(snapshotKey, null)
+
+  if (
+    rawSnapshot &&
+    !unwrapSnapshot(rawSnapshot, { ttlMs, now }) &&
+    !isOversizedSnapshotMarker(rawSnapshot, { ttlMs, now })
+  ) {
+    removeKey(snapshotKey)
+  }
+
+  // Persist pruned history so expired entries don't linger
+  writeJson(historyKey, existingHistory)
 
   changeHistoryActions.setHistory(existingHistory)
   changeHistoryActions.setUnseenChanges(
@@ -163,9 +255,7 @@ export const clearHistory = () => (system) => {
     return
   }
 
-  localStorage.removeItem(getHistoryStorageKey(storageKey))
-  localStorage.removeItem(getSnapshotStorageKey(storageKey))
-  localStorage.removeItem(getViewedStorageKey(storageKey))
+  clearPersistedHistory(storageKey)
 
   changeHistoryActions.setHistory([])
   changeHistoryActions.setUnseenChanges(false)

test/unit/core/plugins/change-history/fn.test.js

@@ -1,10 +1,16 @@
 import {
+  canPersistSnapshot,
   compareSpecs,
+  filterHistoryByTtl,
   formatChangeSummary,
   getStorageKey,
   hashSpec,
+  isOversizedSnapshotMarker,
   resolveRefs,
   stableStringify,
+  unwrapSnapshot,
+  wrapOversizedSnapshotMarker,
+  wrapSnapshot,
 } from "core/plugins/change-history/fn"
 
 describe("change-history fn", () => {
@@ -449,4 +455,56 @@ describe("change-history fn", () => {
       ).toEqual('Schema "Pet": type changed (object → array)')
     })
   })
+
+  describe("snapshot retention helpers", () => {
+    it("wraps and unwraps snapshots with savedAt", () => {
+      const wrapped = wrapSnapshot(baseSpec, 1000)
+      expect(wrapped).toEqual({ savedAt: 1000, spec: baseSpec })
+      expect(unwrapSnapshot(wrapped, { ttlMs: 5000, now: 2000 })).toEqual({
+        savedAt: 1000,
+        spec: baseSpec,
+      })
+    })
+
+    it("supports legacy plain-spec snapshots", () => {
+      expect(unwrapSnapshot(baseSpec, { ttlMs: 1, now: Date.now() })).toEqual({
+        savedAt: null,
+        spec: baseSpec,
+      })
+    })
+
+    it("expires wrapped snapshots past TTL", () => {
+      const wrapped = wrapSnapshot(baseSpec, 1000)
+      expect(unwrapSnapshot(wrapped, { ttlMs: 100, now: 2000 })).toBeNull()
+    })
+
+    it("filters history entries older than TTL", () => {
+      const history = [
+        { id: "1", timestamp: 1000 },
+        { id: "2", timestamp: 5000 },
+      ]
+      expect(filterHistoryByTtl(history, 2000, 6000)).toEqual([
+        { id: "2", timestamp: 5000 },
+      ])
+    })
+
+    it("rejects oversized snapshots and keeps a hash marker", () => {
+      expect(canPersistSnapshot(baseSpec, 10, 1000)).toBe(false)
+      expect(canPersistSnapshot(baseSpec, 1024 * 1024, 1000)).toBe(true)
+
+      const marker = wrapOversizedSnapshotMarker("abc", 1000)
+      expect(marker).toEqual({
+        savedAt: 1000,
+        oversized: true,
+        specHash: "abc",
+      })
+      expect(unwrapSnapshot(marker, { ttlMs: 5000, now: 2000 })).toBeNull()
+      expect(isOversizedSnapshotMarker(marker, { ttlMs: 5000, now: 2000 })).toBe(
+        true
+      )
+      expect(isOversizedSnapshotMarker(marker, { ttlMs: 100, now: 2000 })).toBe(
+        false
+      )
+    })
+  })
 })