@f8team/reel-core 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @f8team/reel-core
 
+## 1.0.4
+
+### Patch Changes
+
+- b476560: Harden HLS playback against repeated fragment request storms by bounding HLS load retries, detecting looped fragment loads, aborting stuck loaders, and surfacing retryable player errors instead of leaving playback stuck in loading.
+
 ## 1.0.3
 
 ### Patch Changes

package/dist/index.cjs

@@ -7,6 +7,7 @@ var RETRYABLE_BY_DEFAULT = {
   decode: false,
   unauthorized: false,
   unsupported: false,
+  "hls-fragment-loop": true,
   internal: false
 };
 function createPlayerError(input) {
@@ -266,6 +267,54 @@ function resolveWithCredentials(policy, url) {
 }
 
 // src/sources/hls.ts
+var REPEATED_FRAGMENT_LOAD_LIMIT = 4;
+var MEDIA_RECOVERY_LIMIT = 1;
+function makeLoadPolicy(options) {
+  return {
+    default: {
+      maxTimeToFirstByteMs: options.maxTimeToFirstByteMs,
+      maxLoadTimeMs: options.maxLoadTimeMs,
+      timeoutRetry: options.timeoutRetry,
+      errorRetry: options.errorRetry
+    }
+  };
+}
+function makeLinearRetry(maxNumRetry, retryDelayMs, maxRetryDelayMs) {
+  return {
+    maxNumRetry,
+    retryDelayMs,
+    maxRetryDelayMs,
+    backoff: "linear"
+  };
+}
+function makeHlsLoadPolicies() {
+  return {
+    manifestLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 1e4,
+      maxLoadTimeMs: 2e4,
+      timeoutRetry: makeLinearRetry(1, 0, 0),
+      errorRetry: makeLinearRetry(1, 1e3, 8e3)
+    }),
+    playlistLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 1e4,
+      maxLoadTimeMs: 2e4,
+      timeoutRetry: makeLinearRetry(1, 0, 0),
+      errorRetry: makeLinearRetry(2, 1e3, 8e3)
+    }),
+    keyLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 8e3,
+      maxLoadTimeMs: 2e4,
+      timeoutRetry: makeLinearRetry(1, 1e3, 8e3),
+      errorRetry: makeLinearRetry(2, 1e3, 8e3)
+    }),
+    fragLoadPolicy: makeLoadPolicy({
+      maxTimeToFirstByteMs: 1e4,
+      maxLoadTimeMs: 3e4,
+      timeoutRetry: makeLinearRetry(1, 0, 0),
+      errorRetry: makeLinearRetry(2, 1e3, 4e3)
+    })
+  };
+}
 var defaultLoad = () => {
   return import('hls.js').then((m) => m.default);
 };
@@ -290,13 +339,17 @@ var HlsLoader = class {
     this.rejectAttach = null;
     this.manifestTimeout = null;
     this.aborted = false;
+    this.lastLoadingFragmentKey = null;
+    this.repeatedFragmentLoadCount = 0;
+    this.repeatedFragmentErrorFired = false;
+    this.mediaRecoveryCount = 0;
     /** `false` idle; `'auto'` → first `LEVEL_SWITCHED` clears; otherwise await this level index. */
     this.qualityAwait = false;
     this.qualitySwitchTimer = null;
     /** Tracks consecutive menu selections so redundant "Auto → Auto" skips the spinner. */
     this.lastChosenQualityWasAuto = false;
     /**
-     * `null` — user chose ABR auto (menu shows "Auto"). Real hls.js still exposes
+     * `null` - user chose ABR auto (menu shows "Auto"). Real hls.js still exposes
      * `currentLevel >= 0` for the playing rendition; we must not mirror that into UI state.
      */
     this.manualLevelIndex = null;
@@ -352,6 +405,7 @@ var HlsLoader = class {
   attachWithHlsJs(Hls, video, source) {
     const hls = new Hls({
       enableWorker: true,
+      ...makeHlsLoadPolicies(),
       xhrSetup: (xhr, url) => this.installXhrWatcher(xhr, url, source)
     });
     this.hls = hls;
@@ -372,27 +426,44 @@ var HlsLoader = class {
         this.onLevelEventuallyStabilized(...args);
         this.refreshActiveQuality();
       };
+      const onFragmentLoading = (...args) => {
+        this.onFragmentLoading(...args);
+      };
+      const onFragmentBuffered = (...args) => {
+        this.resetFragmentLoopGuardFromEvent(...args);
+      };
       const onError = (..._args) => {
-        const data = _args[1] ?? {};
+        const data = this.getHlsEventData(_args);
         const status = data.response?.code;
+        if (this.tryRecoverMediaError(Hls, data)) {
+          return;
+        }
         const isHttpError = typeof status === "number" && status >= 400;
-        if (data.fatal || isHttpError) {
-          const message = data.fatal ? `HLS fatal error: ${data.type ?? "unknown"}` : `HLS load error: HTTP ${status}`;
+        const isTerminalHlsError = this.isTerminalHlsError(data);
+        if (data.fatal || isHttpError || isTerminalHlsError) {
+          const message = this.formatHlsErrorMessage(data, status);
+          this.stopHlsLoading();
           this.options.onError?.({
+            code: this.getHlsErrorCode(data, status),
             message,
             cause: data,
             status,
-            url: data.response?.url ?? data.url
+            url: this.getErrorUrl(data),
+            retryable: this.isRetryableHlsError(data, status)
           });
           settle(() => reject(new Error(message)));
         }
       };
       hls.on(Hls.Events.MANIFEST_PARSED, onParsed);
       hls.on(Hls.Events.LEVEL_SWITCHED, onSwitched);
+      hls.on(Hls.Events.FRAG_LOADING, onFragmentLoading);
+      hls.on(Hls.Events.FRAG_BUFFERED, onFragmentBuffered);
       hls.on(Hls.Events.ERROR, onError);
       this.detachListeners.push(
         () => hls.off(Hls.Events.MANIFEST_PARSED, onParsed),
         () => hls.off(Hls.Events.LEVEL_SWITCHED, onSwitched),
+        () => hls.off(Hls.Events.FRAG_LOADING, onFragmentLoading),
+        () => hls.off(Hls.Events.FRAG_BUFFERED, onFragmentBuffered),
         () => hls.off(Hls.Events.ERROR, onError),
         () => settle(() => reject(makeAbortError()))
       );
@@ -400,6 +471,7 @@ var HlsLoader = class {
       if (timeoutMs > 0) {
         this.manifestTimeout = setTimeout(() => {
           const message = `HLS manifest timeout after ${timeoutMs}ms`;
+          this.stopHlsLoading();
           this.options.onError?.({ message, cause: { type: "timeout" }, url: source.src });
           settle(() => reject(new Error(message)));
         }, timeoutMs);
@@ -414,7 +486,7 @@ var HlsLoader = class {
   }
   /**
    * Wire the readystatechange watcher and remove it as soon as the XHR
-   * completes — without this cleanup hls.js (which spawns one XHR per segment)
+   * completes - without this cleanup hls.js (which spawns one XHR per segment)
    * leaks a closure per request (A1).
    */
   installXhrWatcher(xhr, url, source) {
@@ -440,10 +512,149 @@ var HlsLoader = class {
     };
     xhr.addEventListener("readystatechange", watcher);
   }
-  abort() {
-    if (this.aborted) return;
-    this.aborted = true;
-    this.clearManifestTimeout();
+  getHlsEventData(args) {
+    const data = args[1] ?? args[0];
+    return data !== null && typeof data === "object" ? data : {};
+  }
+  getFragmentUrl(data) {
+    return data.frag?.url ?? data.frag?.relurl ?? data.response?.url ?? data.url;
+  }
+  getErrorUrl(data) {
+    return this.getFragmentUrl(data) ?? this.currentSource?.src;
+  }
+  getFragmentKey(data) {
+    const url = this.getFragmentUrl(data);
+    const frag = data.frag;
+    if (!frag) return url ?? null;
+    const type = frag.type ?? "main";
+    const level = frag.level ?? "unknown-level";
+    const sn = frag.sn ?? "unknown-sn";
+    const cc = frag.cc ?? "unknown-cc";
+    const start = frag.start ?? frag.startPTS ?? "unknown-start";
+    return `${url ?? "unknown-url"}:${type}:${level}:${sn}:${cc}:${start}`;
+  }
+  isTerminalHlsError(data) {
+    switch (data.details) {
+      case "manifestParsingError":
+      case "manifestIncompatibleCodecsError":
+      case "levelEmptyError":
+      case "levelParsingError":
+      case "fragParsingError":
+      case "fragDecryptError":
+      case "keyLoadError":
+      case "keyLoadTimeOut":
+      case "bufferFullError":
+        return true;
+      default:
+        return false;
+    }
+  }
+  formatHlsErrorMessage(data, status) {
+    if (data.fatal) {
+      const type2 = data.type ?? "unknown";
+      const details2 = data.details ? ` (${data.details})` : "";
+      return `HLS fatal error: ${type2}${details2}`;
+    }
+    if (typeof status === "number" && status >= 400) {
+      return `HLS load error: HTTP ${status}${data.details ? ` (${data.details})` : ""}`;
+    }
+    const type = data.type ?? "unknown";
+    const details = data.details ? ` (${data.details})` : "";
+    return `HLS error: ${type}${details}`;
+  }
+  getHlsErrorCode(data, status) {
+    if (status === 401 || status === 403) return "unauthorized";
+    switch (data.details) {
+      case "manifestParsingError":
+      case "manifestIncompatibleCodecsError":
+      case "levelParsingError":
+      case "fragParsingError":
+      case "fragDecryptError":
+        return "decode";
+      default:
+        return "network";
+    }
+  }
+  isRetryableHlsError(data, status) {
+    if (status === 401 || status === 403) return false;
+    if (typeof status === "number" && status >= 400 && status < 500) return false;
+    switch (data.details) {
+      case "manifestParsingError":
+      case "manifestIncompatibleCodecsError":
+      case "levelParsingError":
+      case "fragParsingError":
+      case "fragDecryptError":
+        return false;
+      default:
+        return true;
+    }
+  }
+  isRecoverableMediaError(Hls, data) {
+    if (data.type !== Hls.ErrorTypes.MEDIA_ERROR && data.type !== "mediaError") {
+      return false;
+    }
+    if (!data.fatal) return false;
+    if (this.mediaRecoveryCount >= MEDIA_RECOVERY_LIMIT) return false;
+    if (typeof this.hls?.recoverMediaError !== "function") return false;
+    switch (data.details) {
+      case void 0:
+      case "bufferAppendError":
+      case "bufferAppendingError":
+      case "bufferStalledError":
+      case "bufferSeekOverHole":
+      case "bufferNudgeOnStall":
+      case "bufferFullError":
+        return true;
+      default:
+        return false;
+    }
+  }
+  tryRecoverMediaError(Hls, data) {
+    if (!this.isRecoverableMediaError(Hls, data)) return false;
+    this.mediaRecoveryCount += 1;
+    this.resetFragmentLoopGuard();
+    this.completeQualityAwaitIfBusy();
+    try {
+      this.hls?.recoverMediaError?.();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  onFragmentLoading(...args) {
+    if (this.repeatedFragmentErrorFired) return;
+    const data = this.getHlsEventData(args);
+    const key = this.getFragmentKey(data);
+    if (!key) return;
+    if (key === this.lastLoadingFragmentKey) {
+      this.repeatedFragmentLoadCount += 1;
+    } else {
+      this.lastLoadingFragmentKey = key;
+      this.repeatedFragmentLoadCount = 1;
+    }
+    if (this.repeatedFragmentLoadCount < REPEATED_FRAGMENT_LOAD_LIMIT) return;
+    this.repeatedFragmentErrorFired = true;
+    this.stopHlsLoading();
+    const url = this.getFragmentUrl(data);
+    this.options.onError?.({
+      code: "hls-fragment-loop",
+      message: `HLS fragment repeatedly loading: ${url ?? key}`,
+      cause: data,
+      url
+    });
+  }
+  resetFragmentLoopGuardFromEvent(...args) {
+    const data = this.getHlsEventData(args);
+    if (this.getFragmentKey(data)) {
+      this.resetFragmentLoopGuard();
+    }
+  }
+  resetFragmentLoopGuard() {
+    this.lastLoadingFragmentKey = null;
+    this.repeatedFragmentLoadCount = 0;
+    this.repeatedFragmentErrorFired = false;
+  }
+  abortLiveXhrs() {
     for (const xhr of [...this.liveXhrs]) {
       try {
         xhr.abort();
@@ -451,6 +662,20 @@ var HlsLoader = class {
       }
     }
     this.liveXhrs.clear();
+  }
+  stopHlsLoading() {
+    this.completeQualityAwaitIfBusy();
+    try {
+      this.hls?.stopLoad?.();
+    } catch {
+    }
+    this.abortLiveXhrs();
+  }
+  abort() {
+    if (this.aborted) return;
+    this.aborted = true;
+    this.clearManifestTimeout();
+    this.abortLiveXhrs();
     const reject = this.rejectAttach;
     this.rejectAttach = null;
     reject?.(makeAbortError());
@@ -486,6 +711,8 @@ var HlsLoader = class {
     this.aborted = false;
     this.lastChosenQualityWasAuto = false;
     this.manualLevelIndex = null;
+    this.mediaRecoveryCount = 0;
+    this.resetFragmentLoopGuard();
   }
   clearQualitySwitchTimerOnly() {
     if (this.qualitySwitchTimer !== null) {
@@ -607,7 +834,7 @@ var HlsLoader = class {
     const locked = this.qualities[this.manualLevelIndex] ?? null;
     this.options.onActiveQuality?.(locked, false);
   }
-  /** @internal — for tests. */
+  /** @internal - for tests. */
   _getInternalState() {
     return { source: this.currentSource, qualities: this.qualities };
   }
@@ -1248,7 +1475,14 @@ function createPlayer(options = {}, internal = {}) {
       onUnauthorized: (e) => emitUnauthorized(e),
       onQualities: (q) => setQualities(q),
       onActiveQuality: (q, auto) => setActiveQuality(q, auto),
-      onError: (err) => applyError(createPlayerError({ ...err, code: "network" })),
+      onError: (err) => {
+        const playerError = createPlayerError({ ...err, code: err.code ?? "network" });
+        if (status === "loading") {
+          dispatch({ type: "loadFailed", error: playerError });
+          return;
+        }
+        dispatch({ type: "runtimeError", error: playerError });
+      },
       onQualitySwitch: (active) => bus.emit("qualityswitch", { active })
     })
   );