rx-player 3.25.2 → 3.26.3-dev.2022021400

package/src/core/fetchers/segment/segment_fetcher.ts

@@ -14,224 +14,443 @@
  * limitations under the License.
  */
 
+import { Observable } from "rxjs";
+import config from "../../../config";
 import {
-  concat as observableConcat,
-  Observable,
-  of as observableOf,
-  Subject,
-} from "rxjs";
+  formatError,
+  ICustomError,
+} from "../../../errors";
+import log from "../../../log";
+import Manifest, {
+  Adaptation,
+  getLoggableSegmentId,
+  ISegment,
+  Period,
+  Representation,
+} from "../../../manifest";
 import {
-  catchError,
-  filter,
-  finalize,
-  mergeMap,
-  share,
-  tap,
-} from "rxjs/operators";
-import { formatError } from "../../../errors";
-import { ISegment } from "../../../manifest";
-import {
-  ISegmentParserInitSegment,
-  ISegmentParserSegment,
-  ITransportPipelines,
+  IChunkCompleteInformation,
+  ISegmentLoadingProgressInformation,
+  ISegmentParserParsedInitChunk,
+  ISegmentParserParsedMediaChunk,
+  ISegmentPipeline,
 } from "../../../transports";
 import arrayIncludes from "../../../utils/array_includes";
-import assertUnreachable from "../../../utils/assert_unreachable";
 import idGenerator from "../../../utils/id_generator";
 import InitializationSegmentCache from "../../../utils/initialization_segment_cache";
+import isNullOrUndefined from "../../../utils/is_null_or_undefined";
+import objectAssign from "../../../utils/object_assign";
+import TaskCanceller, {
+  CancellationSignal,
+} from "../../../utils/task_canceller";
 import {
-  IABRMetricsEvent,
-  IABRRequestBeginEvent,
-  IABRRequestEndEvent,
-  IABRRequestProgressEvent,
+  IABRMetricsEventValue,
+  IABRRequestBeginEventValue,
+  IABRRequestEndEventValue,
+  IABRRequestProgressEventValue,
 } from "../../abr";
 import { IBufferType } from "../../segment_buffers";
-import { IBackoffOptions } from "../utils/try_urls_with_backoff";
-import createSegmentLoader, {
-  ISegmentLoaderChunk,
-  ISegmentLoaderChunkComplete,
-  ISegmentLoaderContent,
-  ISegmentLoaderData,
-  ISegmentLoaderWarning,
-} from "./create_segment_loader";
-
-/**
- * Event sent when the segment request needs to be renewed (e.g. due to an HTTP
- * error).
- */
-export type ISegmentFetcherWarning = ISegmentLoaderWarning;
-
-/**
- * Event sent when a new "chunk" of the segment is available.
- * A segment can contain n chunk(s) for n >= 0.
- */
-export interface ISegmentFetcherChunkEvent<T> {
-  type : "chunk";
-  /** Parse the downloaded chunk. */
-  parse : (initTimescale? : number) => Observable<ISegmentParserInitSegment<T> |
-                                                  ISegmentParserSegment<T>>;
-}
+import errorSelector from "../utils/error_selector";
+import { tryURLsWithBackoff } from "../utils/try_urls_with_backoff";
 
-/**
- * Event sent when all "chunk" of the segments have been communicated through
- * `ISegmentFetcherChunkEvent` events.
- */
-export interface ISegmentFetcherChunkCompleteEvent { type: "chunk-complete" }
-
-/** Event sent by the SegmentFetcher when fetching a segment. */
-export type ISegmentFetcherEvent<T> = ISegmentFetcherChunkCompleteEvent |
-                                      ISegmentFetcherChunkEvent<T> |
-                                      ISegmentFetcherWarning;
-
-export type ISegmentFetcher<T> = (content : ISegmentLoaderContent) =>
-                                   Observable<ISegmentFetcherEvent<T>>;
+const { DEFAULT_MAX_REQUESTS_RETRY_ON_ERROR,
+        DEFAULT_MAX_REQUESTS_RETRY_ON_OFFLINE,
+        INITIAL_BACKOFF_DELAY_BASE,
+        MAX_BACKOFF_DELAY_BASE } = config;
 
 const generateRequestID = idGenerator();
 
 /**
- * Create a function which will fetch and parse segments.
+ * Create an `ISegmentFetcher` object which will allow to easily fetch and parse
+ * segments.
+ * An `ISegmentFetcher` also implements a retry mechanism, based on the given
+ * `options` argument, which may retry a segment request when it fails.
+ *
  * @param {string} bufferType
  * @param {Object} transport
- * @param {Subject} requests$
+ * @param {Object} callbacks
  * @param {Object} options
  * @returns {Function}
  */
-export default function createSegmentFetcher<T>(
+export default function createSegmentFetcher<TLoadedFormat, TSegmentDataType>(
   bufferType : IBufferType,
-  transport : ITransportPipelines,
-  requests$ : Subject<IABRMetricsEvent |
-                      IABRRequestBeginEvent |
-                      IABRRequestProgressEvent |
-                      IABRRequestEndEvent>,
-  options : IBackoffOptions
-) : ISegmentFetcher<T> {
+  pipeline : ISegmentPipeline<TLoadedFormat, TSegmentDataType>,
+  callbacks : ISegmentFetcherCreatorCallbacks,
+  options : ISegmentFetcherOptions
+) : ISegmentFetcher<TSegmentDataType> {
+  /**
+   * Cache audio and video initialization segments.
+   * This allows to avoid doing too many requests for what are usually very
+   * small files.
+   */
   const cache = arrayIncludes(["audio", "video"], bufferType) ?
-    new InitializationSegmentCache<any>() :
+    new InitializationSegmentCache<TLoadedFormat>() :
     undefined;
-  const segmentLoader = createSegmentLoader<any>(transport[bufferType].loader,
-                                                 cache,
-                                                 options);
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-  const segmentParser = transport[bufferType].parser as any; // deal with it
+
+  const { loadSegment, parseSegment } = pipeline;
 
   /**
-   * Process the segmentLoader observable to adapt it to the the rest of the
-   * code:
-   *   - use the requests subject for network requests and their progress
-   *   - use the warning$ subject for retries' error messages
-   *   - only emit the data
+   * Fetch a specific segment.
+   *
+   * This function returns an Observable which will fetch segments on
+   * subscription.
+   * If the corresponding request fails, it may retry it based on the given
+   * options.
+   *
+   * This Observable will emit various events during that request lifecycle and
+   * throw if the segment request(s) (including potential retries) fail.
+   * The Observable will automatically complete once no events are left to be
+   * sent.
    * @param {Object} content
    * @returns {Observable}
    */
   return function fetchSegment(
     content : ISegmentLoaderContent
-  ) : Observable<ISegmentFetcherEvent<T>> {
-    const id = generateRequestID();
-    let requestBeginSent = false;
-    return segmentLoader(content).pipe(
-      tap((arg) => {
-        switch (arg.type) {
-          case "metrics": {
-            requests$.next(arg);
-            break;
+  ) : Observable<ISegmentFetcherEvent<TSegmentDataType>> {
+    const { segment } = content;
+
+    // used by logs
+    const segmentIdString = getLoggableSegmentId(content);
+
+    return new Observable((obs) => {
+      const requestId = generateRequestID();
+      const canceller = new TaskCanceller();
+
+      /**
+       * If the request succeeded, set to the corresponding
+       * `IChunkCompleteInformation` object.
+       * For any other completion cases: if the request either failed, was
+       * cancelled or just if no request was needed, set to `null`.
+       *
+       * Stays to `undefined` when the request is still pending.
+       */
+      let requestInfo : IChunkCompleteInformation | null | undefined;
+
+      /**
+       * Array containing one entry per loaded chunk, in chronological order.
+       * The boolean indicates if the chunk has been parsed at least once.
+       *
+       * This is used to know when all loaded chunks have been parsed, which
+       * can be useful to e.g. construct metrics about the loaded segment.
+       */
+      const parsedChunks : boolean[] = [];
+
+      /**
+       * Addition of the duration of each encountered and parsed chunks.
+       * Allows to have an idea of the real duration of the full segment once
+       * all chunks have been parsed.
+       *
+       * `undefined` if at least one of the parsed chunks has unknown duration.
+       */
+      let segmentDurationAcc : number | undefined = 0;
+
+      /** Set to `true` once network metrics have been sent. */
+      let metricsSent = false;
+
+      const loaderCallbacks = {
+        /**
+         * Callback called when the segment loader has progress information on
+         * the request.
+         * @param {Object} info
+         */
+        onProgress(info : ISegmentLoadingProgressInformation) : void {
+          if (info.totalSize !== undefined && info.size < info.totalSize) {
+            callbacks.onProgress?.({ duration: info.duration,
+                                     size: info.size,
+                                     totalSize: info.totalSize,
+                                     timestamp: performance.now(),
+                                     id: requestId });
           }
+        },
+
+        /**
+         * Callback called when the segment is communicated by the loader
+         * through decodable sub-segment(s) called chunk(s), with a chunk in
+         * argument.
+         * @param {*} chunkData
+         */
+        onNewChunk(chunkData : TLoadedFormat) : void {
+          obs.next({ type: "chunk" as const,
+                     parse: generateParserFunction(chunkData, true) });
+        },
+      };
+
+      // Retrieve from cache if it exists
+      const cached = cache !== undefined ? cache.get(content) :
+                                           null;
+      if (cached !== null) {
+        log.debug("SF: Found wanted segment in cache", segmentIdString);
+        obs.next({ type: "chunk" as const,
+                   parse: generateParserFunction(cached, false) });
+        obs.next({ type: "chunk-complete" as const });
+        obs.complete();
+        return undefined;
+      }
 
-          case "request": {
-            const { value } = arg;
+      log.debug("SF: Beginning request", segmentIdString);
+      callbacks.onRequestBegin?.({ requestTimestamp: performance.now(),
+                                   id: requestId,
+                                   content });
 
-            // format it for ABR Handling
-            const segment : ISegment|undefined = value.segment;
-            if (segment === undefined) {
-              return;
+      tryURLsWithBackoff(segment.mediaURLs ?? [null],
+                         callLoaderWithUrl,
+                         objectAssign({ onRetry }, options),
+                         canceller.signal)
+        .then((res) => {
+          log.debug("SF: Segment request ended with success", segmentIdString);
+
+          if (res.resultType === "segment-loaded") {
+            const loadedData = res.resultData.responseData;
+            if (cache !== undefined) {
+              cache.add(content, res.resultData.responseData);
             }
-            requestBeginSent = true;
-            requests$.next({ type: "requestBegin",
-                             value: { duration: segment.duration,
-                                      time: segment.time,
-                                      requestTimestamp: performance.now(),
-                                      id } });
-            break;
+            obs.next({ type: "chunk" as const,
+                       parse: generateParserFunction(loadedData, false) });
+          } else if (res.resultType === "segment-created") {
+            obs.next({ type: "chunk" as const,
+                       parse: generateParserFunction(res.resultData, false) });
           }
 
-          case "progress": {
-            const { value } = arg;
-            if (value.totalSize != null && value.size < value.totalSize) {
-              requests$.next({ type: "progress",
-                               value: { duration: value.duration,
-                                        size: value.size,
-                                        totalSize: value.totalSize,
-                                        timestamp: performance.now(),
-                                        id } });
-            }
-            break;
+          log.debug("SF: Segment request ended with success", segmentIdString);
+          obs.next({ type: "chunk-complete" as const });
+
+          if (res.resultType !== "segment-created") {
+            requestInfo = res.resultData;
+            sendNetworkMetricsIfAvailable();
+          } else {
+            requestInfo = null;
           }
-        }
-      }),
 
-      finalize(() => {
-        if (requestBeginSent) {
-          requests$.next({ type: "requestEnd", value: { id } });
-        }
-      }),
-
-      filter((e) : e is ISegmentLoaderChunk |
-                        ISegmentLoaderChunkComplete |
-                        ISegmentLoaderData<T> |
-                        ISegmentFetcherWarning => {
-        switch (e.type) {
-          case "warning":
-          case "chunk":
-          case "chunk-complete":
-          case "data":
-            return true;
-          case "progress":
-          case "metrics":
-          case "request":
-            return false;
-          default:
-            assertUnreachable(e);
-        }
-      }),
-      mergeMap((evt) => {
-        if (evt.type === "warning") {
-          return observableOf(evt);
-        }
-        if (evt.type === "chunk-complete") {
-          return observableOf({ type: "chunk-complete" as const });
+          if (!canceller.isUsed) {
+            // The current Observable could have been canceled as a result of one
+            // of the previous `next` calls. In that case, we don't want to send
+            // a "requestEnd" again as it has already been sent on cancellation.
+            //
+            // Note that we only perform this check for `onRequestEnd` on
+            // purpose. Observable's events should have been ignored by RxJS if
+            // the Observable has already been canceled and we don't care if
+            // `"metrics"` is sent there.
+            callbacks.onRequestEnd?.({ id: requestId });
+          }
+          obs.complete();
+        })
+        .catch((err) => {
+          log.debug("SF: Segment request failed", segmentIdString);
+          requestInfo = null;
+          obs.error(errorSelector(err));
+        });
+
+      return () => {
+        if (requestInfo !== undefined) {
+          return; // Request already terminated
         }
+        log.debug("SF: Segment request cancelled", segmentIdString);
+        requestInfo = null;
+        canceller.cancel();
+        callbacks.onRequestEnd?.({ id: requestId });
+      };
 
-        const isChunked = evt.type === "chunk";
-        const data = {
-          type: "chunk" as const,
-          /**
-           * Parse the loaded data.
-           * @param {Object} [initTimescale]
-           * @returns {Observable}
-           */
-          parse(initTimescale? : number) : Observable<ISegmentParserInitSegment<T> |
-                                                      ISegmentParserSegment<T>> {
-            const response = { data: evt.value.responseData, isChunked };
-            /* eslint-disable @typescript-eslint/no-unsafe-call */
-            /* eslint-disable @typescript-eslint/no-unsafe-member-access */
-            /* eslint-disable @typescript-eslint/no-unsafe-return */
-            return segmentParser({ response, initTimescale, content })
-            /* eslint-enable @typescript-eslint/no-unsafe-call */
-            /* eslint-enable @typescript-eslint/no-unsafe-member-access */
-            /* eslint-enable @typescript-eslint/no-unsafe-return */
-              .pipe(catchError((error: unknown) => {
-                throw formatError(error, { defaultCode: "PIPELINE_PARSE_ERROR",
-                                           defaultReason: "Unknown parsing error" });
-              }));
-          },
+      /**
+       * Call a segment loader for the given URL with the right arguments.
+       * @param {string|null} url
+       * @param {Object} cancellationSignal
+       * @returns {Promise}
+       */
+      function callLoaderWithUrl(
+        url : string | null,
+        cancellationSignal: CancellationSignal
+      ) {
+        return loadSegment(url, content, cancellationSignal, loaderCallbacks);
+      }
+
+      /**
+       * Generate function allowing to parse a loaded segment.
+       * @param {*} data
+       * @param {Boolean} isChunked
+       * @returns {Function}
+       */
+      function generateParserFunction(data : TLoadedFormat, isChunked : boolean)  {
+        parsedChunks.push(false);
+        const parsedChunkId = parsedChunks.length - 1;
+        return function parse(initTimescale? : number) :
+          ISegmentParserParsedInitChunk<TSegmentDataType> |
+          ISegmentParserParsedMediaChunk<TSegmentDataType>
+        {
+          const loaded = { data, isChunked };
+
+          try {
+            const parsed = parseSegment(loaded, content, initTimescale);
+
+            if (!parsedChunks[parsedChunkId]) {
+              segmentDurationAcc = segmentDurationAcc !== undefined &&
+                                   parsed.segmentType === "media" &&
+                                   parsed.chunkInfos !== null &&
+                                   parsed.chunkInfos.duration !== undefined ?
+                segmentDurationAcc + parsed.chunkInfos.duration :
+                undefined;
+              parsedChunks[parsedChunkId] = true;
+
+              sendNetworkMetricsIfAvailable();
+            }
+            return parsed;
+          } catch (error) {
+            throw formatError(error, { defaultCode: "PIPELINE_PARSE_ERROR",
+                                       defaultReason: "Unknown parsing error" });
+          }
         };
+      }
 
-        if (isChunked) {
-          return observableOf(data);
+      /**
+       * Function called when the function request is retried.
+       * @param {*} err
+       */
+      function onRetry(err: unknown) : void {
+        obs.next({ type: "retry" as const,
+                   value: errorSelector(err) });
+      }
+
+      /**
+       * Send netork metrics if they haven't yet been sent and if all data to
+       * define them is available.
+       */
+      function sendNetworkMetricsIfAvailable() : void {
+        if (metricsSent) {
+          return;
+        }
+        if (!isNullOrUndefined(requestInfo) &&
+            requestInfo.size !== undefined &&
+            requestInfo.requestDuration !== undefined &&
+            parsedChunks.length > 0 &&
+            parsedChunks.every(isParsed => isParsed))
+        {
+          metricsSent = true;
+          callbacks.onMetrics?.({ size: requestInfo.size,
+                                  requestDuration: requestInfo.requestDuration,
+                                  content,
+                                  segmentDuration: segmentDurationAcc });
         }
-        return observableConcat(observableOf(data),
-                                observableOf({ type: "chunk-complete" as const }));
-      }),
-      share() // avoid multiple side effects if multiple subs
-    );
+      }
+    });
   };
 }
+
+export type ISegmentFetcher<TSegmentDataType> = (content : ISegmentLoaderContent) =>
+  Observable<ISegmentFetcherEvent<TSegmentDataType>>;
+
+/** Event sent by the SegmentFetcher when fetching a segment. */
+export type ISegmentFetcherEvent<TSegmentDataType> =
+  ISegmentFetcherChunkEvent<TSegmentDataType> |
+  ISegmentFetcherChunkCompleteEvent |
+  ISegmentFetcherRetry;
+
+/**
+ * Event sent when a new "chunk" of the segment is available.
+ * A segment can contain n chunk(s) for n >= 0.
+ */
+export interface ISegmentFetcherChunkEvent<TSegmentDataType> {
+  type : "chunk";
+  /** Parse the downloaded chunk. */
+  /**
+   * Parse the downloaded chunk.
+   *
+   * Take in argument the timescale value that might have been obtained by
+   * parsing an initialization segment from the same Representation.
+   * Can be left to `undefined` if unknown or inexistant, segment parsers should
+   * be resilient and still work without that information.
+   *
+   * @param {number} initTimescale
+   * @returns {Object}
+   */
+  parse(initTimescale? : number) : ISegmentParserParsedInitChunk<TSegmentDataType> |
+                                   ISegmentParserParsedMediaChunk<TSegmentDataType>;
+}
+
+/**
+ * Event sent when all "chunk" of the segments have been communicated through
+ * `ISegmentFetcherChunkEvent` events.
+ */
+export interface ISegmentFetcherChunkCompleteEvent { type: "chunk-complete" }
+
+/** Content used by the segment loader as a context to load a new segment. */
+export interface ISegmentLoaderContent { manifest : Manifest;
+                                         period : Period;
+                                         adaptation : Adaptation;
+                                         representation : Representation;
+                                         segment : ISegment; }
+
+/**
+ * An Error happened while loading which led to a retry.
+ * The request is retried from scratch.
+ */
+export interface ISegmentFetcherRetry { type : "retry";
+                                        value : ICustomError; }
+
+/**
+ * Callbacks that can be bound when creating an `ISegmentFetcher`.
+ * Those allows to be notified of an `ISegmentFetcher` various lifecycles and of
+ * network information.
+ */
+export interface ISegmentFetcherCreatorCallbacks {
+  /** Called when a segment request begins. */
+  onRequestBegin? : (arg : IABRRequestBeginEventValue) => void;
+  /** Called when progress information is available on a pending segment request. */
+  onProgress? : (arg : IABRRequestProgressEventValue) => void;
+  /**
+   * Called when a segment request ends (either because it completed, it failed
+   * or was canceled).
+   */
+  onRequestEnd? : (arg : IABRRequestEndEventValue) => void;
+  /**
+   * Called when network metrics linked to a segment request are available,
+   * once the request has terminated.
+   * This callback may be called before or after the corresponding
+   * `onRequestEnd` callback, you should not rely on the order between the two.
+   */
+  onMetrics? : (arg : IABRMetricsEventValue) => void;
+}
+
+/** Options allowing to configure an `ISegmentFetcher`'s behavior. */
+export interface ISegmentFetcherOptions {
+  /**
+   * Initial delay to wait if a request fails before making a new request, in
+   * milliseconds.
+   */
+  baseDelay : number;
+  /**
+   * Maximum delay to wait if a request fails before making a new request, in
+   * milliseconds.
+   */
+  maxDelay : number;
+  /**
+   * Maximum number of retries to perform on "regular" errors (e.g. due to HTTP
+   * status, integrity errors, timeouts...).
+   */
+  maxRetryRegular : number;
+  /**
+   * Maximum number of retries to perform when it appears that the user is
+   * currently offline.
+   */
+  maxRetryOffline : number;
+}
+
+/**
+ * @param {string} bufferType
+ * @param {Object}
+ * @returns {Object}
+ */
+export function getSegmentFetcherOptions(
+  bufferType : string,
+  { maxRetryRegular,
+    maxRetryOffline,
+    lowLatencyMode } : { maxRetryRegular? : number | undefined;
+                         maxRetryOffline? : number | undefined;
+                         lowLatencyMode : boolean; }
+) : ISegmentFetcherOptions {
+  return { maxRetryRegular: bufferType === "image" ? 0 :
+                            maxRetryRegular ?? DEFAULT_MAX_REQUESTS_RETRY_ON_ERROR,
+           maxRetryOffline: maxRetryOffline ?? DEFAULT_MAX_REQUESTS_RETRY_ON_OFFLINE,
+           baseDelay: lowLatencyMode ? INITIAL_BACKOFF_DELAY_BASE.LOW_LATENCY :
+                                       INITIAL_BACKOFF_DELAY_BASE.REGULAR,
+           maxDelay: lowLatencyMode ? MAX_BACKOFF_DELAY_BASE.LOW_LATENCY :
+                                      MAX_BACKOFF_DELAY_BASE.REGULAR };
+}