fix: recover from QuotaExceededError by evicting back buffer and retrying append

When a SourceBuffer append throws QuotaExceededError, intercept the error
before it propagates, evict the minimum number of back buffer segments
needed to fit the new data, and retry the append with the original data
still in memory — avoiding the re-download loop that plagues hls.js
upstream (#6776, #6711).

Eviction uses actual byte sizes from the fragment tracker rather than
time-based estimates, so the calculation is exact regardless of bitrate
or ABR level switches. If eviction + retry fails (e.g. no back buffer
to evict), falls through to the existing BUFFER_FULL_ERROR path.

Changes:
- buffer-controller: on QuotaExceededError, calculate eviction target
  and queue a remove + retry append instead of emitting an error
- fragment-tracker: add getBackBufferEvictionEnd() which walks buffered
  fragments oldest-first accumulating byte sizes to find the minimum
  eviction point
- buffer-operation-queue: add insertNext() to queue operations after
  the current one for remove-then-retry sequencing

Author: alchemyyy

src/controller/buffer-controller.ts

@@ -853,6 +853,7 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
     }
 
     const fragStart = (part || frag).start;
+    let quotaEvictionAttempted = false;
     const operation: BufferOperation = {
       label: `append-${type}`,
       execute: () => {
@@ -900,6 +901,35 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
       },
       onError: (error: Error) => {
         this.clearBufferAppendTimeoutId(this.tracks[type]);
+
+        const isQuotaError =
+          (error as DOMException).code === DOMException.QUOTA_EXCEEDED_ERR ||
+          error.name == 'QuotaExceededError' ||
+          `quota` in error;
+
+        // On QuotaExceededError: evict back buffer and retry the append once
+        // instead of emitting an error that forces the segment to be re-downloaded.
+        if (isQuotaError && !quotaEvictionAttempted) {
+          const evictEnd = this.getBackBufferEvictionTarget(
+            type,
+            data.byteLength,
+            frag.type,
+          );
+          if (evictEnd > 0) {
+            quotaEvictionAttempted = true;
+            this.log(
+              `QuotaExceededError on "${type}" append sn: ${sn} — evicting back buffer to ${evictEnd.toFixed(3)}s and retrying`,
+            );
+            // Insert a remove operation followed by a retry of this append
+            // right after the current (failed) operation in the queue.
+            // When shiftAndExecuteNext removes the failed op, the remove runs
+            // first, then the retry append with the same data.
+            const removeOp = this.getFlushOp(type, 0, evictEnd);
+            this.insertNext([removeOp, operation], type);
+            return;
+          }
+        }
+
         // in case any error occured while appending, put back segment in segments table
         const event: ErrorData = {
           type: ErrorTypes.MEDIA_ERROR,
@@ -914,13 +944,9 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
           fatal: false,
         };
         const mediaError = this.media?.error;
-        if (
-          (error as DOMException).code === DOMException.QUOTA_EXCEEDED_ERR ||
-          error.name == 'QuotaExceededError' ||
-          `quota` in error
-        ) {
+        if (isQuotaError) {
           // QuotaExceededError: http://www.w3.org/TR/html5/infrastructure.html#quotaexceedederror
-          // let's stop appending any segments, and report BUFFER_FULL_ERROR error
+          // Eviction was already attempted or not possible — report BUFFER_FULL_ERROR
           event.details = ErrorDetails.BUFFER_FULL_ERROR;
         } else if (
           (error as DOMException).code === DOMException.INVALID_STATE_ERR &&
@@ -1198,6 +1224,26 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
     }
   }
 
+  // Returns the end position to evict back buffer to on QuotaExceededError,
+  // or 0 if there is nothing to evict. Delegates to the fragment tracker which
+  // walks buffered fragments oldest-first using actual byte sizes to find the
+  // minimum eviction needed to fit the new segment.
+  private getBackBufferEvictionTarget(
+    type: SourceBufferName,
+    segmentBytes: number,
+    playlistType: PlaylistLevelType,
+  ): number {
+    const { media } = this;
+    if (!media) {
+      return 0;
+    }
+    return this.fragmentTracker.getBackBufferEvictionEnd(
+      media.currentTime,
+      playlistType,
+      segmentBytes,
+    );
+  }
+
   private resetAppendErrors() {
     this.appendErrors = {
       audio: 0,
@@ -1940,6 +1986,12 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
     }
   }
 
+  private insertNext(operations: BufferOperation[], type: SourceBufferName) {
+    if (this.operationQueue) {
+      this.operationQueue.insertNext(operations, type);
+    }
+  }
+
   private appendBlocker(type: SourceBufferName): Promise<void> | undefined {
     if (this.operationQueue) {
       return this.operationQueue.appendBlocker(type);

src/controller/buffer-operation-queue.ts

@@ -79,6 +79,14 @@ export default class BufferOperationQueue {
     );
   }
 
+  public insertNext(operations: BufferOperation[], type: SourceBufferName) {
+    if (this.queues === null) {
+      return;
+    }
+    // Insert after the current (index 0) operation so they execute next
+    this.queues[type].splice(1, 0, ...operations);
+  }
+
   public unblockAudio(op: BufferOperation) {
     if (this.queues === null) {
       return;

src/controller/fragment-tracker.ts

@@ -482,6 +482,60 @@ export class FragmentTracker implements ComponentAPI {
     return !!this.activePartLists[type]?.length;
   }
 
+  /**
+   * Returns the eviction end position needed to free at least `bytesNeeded`
+   * from the back buffer, or 0 if not enough data is available.
+   * Walks buffered fragments oldest-first, accumulating actual byte sizes.
+   */
+  public getBackBufferEvictionEnd(
+    beforePosition: number,
+    levelType: PlaylistLevelType,
+    bytesNeeded: number,
+  ): number {
+    const { fragments } = this;
+
+    // Collect back buffer fragments with known byte sizes
+    let count = 0;
+    const candidates: FragmentEntity[] = [];
+    for (const key of Object.keys(fragments)) {
+      const entity = fragments[key];
+      if (!entity || !entity.buffered || entity.body.type !== levelType) {
+        continue;
+      }
+      const frag = entity.body;
+      if (frag.end <= beforePosition && frag.byteLength) {
+        candidates[count++] = entity;
+      }
+    }
+
+    if (count === 0) {
+      return 0;
+    }
+
+    // Sort by sn (oldest first) — small array of references, no data copying.
+    // Candidates are unsorted because this.fragments is a hash map keyed by
+    // "type_level_sn", and Object.keys() returns insertion order which depends
+    // on when each fragment was loaded, not its position in the timeline.
+    // ABR level switches and seeks can cause fragments to load out of order.
+    candidates.length = count;
+    candidates.sort((a, b) => (a.body.sn as number) - (b.body.sn as number));
+
+    // Walk oldest-first, accumulating bytes until we have enough
+    let bytesFreed = 0;
+    let evictEnd = 0;
+    for (let i = 0; i < count; i++) {
+      const frag = candidates[i].body;
+      bytesFreed += frag.byteLength!;
+      evictEnd = frag.end;
+      if (bytesFreed >= bytesNeeded) {
+        return evictEnd;
+      }
+    }
+
+    // Not enough to fully cover bytesNeeded, return what we have
+    return evictEnd > 0 ? evictEnd : 0;
+  }
+
   public removeFragmentsInRange(
     start: number,
     end: number,