rx-player 3.33.0 → 3.33.1

package/src/core/fetchers/utils/schedule_request.ts

@@ -1,493 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { isOffline } from "../../../compat";
-import {
-  CustomLoaderError,
-  isKnownError,
-  NetworkErrorTypes,
-  RequestError,
-} from "../../../errors";
-import log from "../../../log";
-import { ICdnMetadata } from "../../../parsers/manifest";
-import cancellableSleep from "../../../utils/cancellable_sleep";
-import getFuzzedDelay from "../../../utils/get_fuzzed_delay";
-import noop from "../../../utils/noop";
-import TaskCanceller, {
-  CancellationSignal,
-} from "../../../utils/task_canceller";
-import CdnPrioritizer from "../cdn_prioritizer";
-
-/**
- * Called on a loader error.
- * Returns whether the loader request should be retried.
- *
- * TODO the notion of retrying or not could be transport-specific (e.g. 412 are
- * mainly used for Smooth contents) and thus as part of the transport code (e.g.
- * by rejecting with an error always having a `canRetry` property?).
- * Or not, to ponder.
- *
- * @param {Error} error
- * @returns {Boolean} - If true, the request can be retried.
- */
-function shouldRetry(error : unknown) : boolean {
-  if (error instanceof RequestError) {
-    if (error.type === NetworkErrorTypes.ERROR_HTTP_CODE) {
-      return error.status >= 500 ||
-             error.status === 404 ||
-             error.status === 415 || // some CDN seems to use that code when
-                                     // requesting low-latency segments too much
-                                     // in advance
-             error.status === 412;
-    }
-    return error.type === NetworkErrorTypes.TIMEOUT ||
-           error.type === NetworkErrorTypes.ERROR_EVENT;
-  } else if (error instanceof CustomLoaderError) {
-    if (typeof error.canRetry === "boolean") {
-      return error.canRetry;
-    }
-    if (error.xhr !== undefined) {
-      return error.xhr.status >= 500 ||
-             error.xhr.status === 404 ||
-             error.xhr.status === 415 || // some CDN seems to use that code when
-                                         // requesting low-latency segments too much
-                                         // in advance
-             error.xhr.status === 412;
-    }
-    return false;
-  }
-  return isKnownError(error) && error.code === "INTEGRITY_ERROR";
-}
-
-/**
- * Returns true if we're pretty sure that the current error is due to the
- * user being offline.
- * @param {Error} error
- * @returns {Boolean}
- */
-function isOfflineRequestError(error : unknown) : boolean {
-  if (error instanceof RequestError) {
-    return error.type === NetworkErrorTypes.ERROR_EVENT &&
-           isOffline();
-  } else if (error instanceof CustomLoaderError) {
-    return error.isOfflineError;
-  }
-  return false; // under doubt, return false
-}
-
-/** Settings to give to the backoff functions to configure their behavior. */
-export interface IBackoffSettings {
-  /**
-   * 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;
-  /** Callback called when a request is retried. */
-  onRetry : (err : unknown) => void;
-}
-
-const enum REQUEST_ERROR_TYPES { None,
-                                 Regular,
-                                 Offline }
-
-/**
- * Guess the type of error obtained.
- * @param {*} error
- * @returns {number}
- */
-function getRequestErrorType(error : unknown) : REQUEST_ERROR_TYPES {
-  return isOfflineRequestError(error) ? REQUEST_ERROR_TYPES.Offline :
-                                        REQUEST_ERROR_TYPES.Regular;
-}
-
-/**
- * Specific algorithm used to perform segment and manifest requests.
- *
- * Here how it works:
- *
- *   1. You give it one or multiple of the CDN available for the resource you
- *      want to request (from the most important one to the least important),
- *      a callback doing the request with the chosen CDN in argument, and some
- *      options.
- *
- *   2. it tries to call the request callback with the most prioritized CDN
- *      first:
- *        - if it works as expected, it resolves the returned Promise with that
- *          request's response.
- *        - if it fails, it calls ther `onRetry` callback given with the
- *          corresponding error, un-prioritize that CDN and try with the new
- *          most prioritized CDN.
- *
- *      Each CDN might be retried multiple times, depending on the nature of the
- *      error and the Configuration given.
- *
- *      Multiple retries of the same CDN are done after a delay to avoid
- *      overwhelming it, this is what we call a "backoff". That delay raises
- *      exponentially as multiple consecutive errors are encountered on this
- *      CDN.
- *
- * @param {Array.<string>|null} cdns - The different CDN on which the
- * wanted resource is available. `scheduleRequestWithCdns` will call the
- * `performRequest` callback with the right element from that array if different
- * from `null`.
- *
- * Can be set to `null` when that resource is not reachable through a CDN, in
- * which case the `performRequest` callback may be called with `null`.
- * @param {Object|null} cdnPrioritizer - Interface allowing to give the priority
- * between multiple CDNs.
- * @param {Function} performRequest - Callback implementing the request in
- * itself. Resolving when the resource request succeed and rejecting with the
- * corresponding error when the request failed.
- * @param {Object} options - Configuration allowing to tweak the number on which
- * the algorithm behind `scheduleRequestWithCdns` bases itself.
- * @param {Object} cancellationSignal - CancellationSignal allowing to cancel
- * the logic of `scheduleRequestWithCdns`.
- * To trigger if the resource is not needed anymore.
- * @returns {Promise} - Promise resolving, with the corresponding
- * `performRequest`'s data, when the resource request succeed and rejecting in
- * the following scenarios:
- *   - `scheduleRequestWithCdns` has been cancelled due to `cancellationSignal`
- *     being triggered. In that case a `CancellationError` is thrown.
- *
- *   - The resource request(s) failed and will not be retried anymore.
- */
-export async function scheduleRequestWithCdns<T>(
-  cdns : ICdnMetadata[] | null,
-  cdnPrioritizer : CdnPrioritizer | null,
-  performRequest : (
-    cdn : ICdnMetadata | null,
-    cancellationSignal : CancellationSignal
-  ) => Promise<T>,
-  options : IBackoffSettings,
-  cancellationSignal : CancellationSignal
-) : Promise<T> {
-  if (cancellationSignal.cancellationError !== null) {
-    return Promise.reject(cancellationSignal.cancellationError);
-  }
-
-  const { baseDelay,
-          maxDelay,
-          maxRetryRegular,
-          maxRetryOffline,
-          onRetry } = options;
-
-  if (cdns !== null && cdns.length === 0) {
-    log.warn("Fetchers: no CDN given to `scheduleRequestWithCdns`.");
-  }
-
-  const missedAttempts : Map<ICdnMetadata | null, ICdnAttemptMetadata> = new Map();
-  const initialCdnToRequest = getCdnToRequest();
-  if (initialCdnToRequest === undefined) {
-    throw new Error("No CDN to request");
-  }
-  return requestCdn(initialCdnToRequest);
-
-  /**
-   * Returns what is now the most prioritary CDN to request the wanted resource.
-   *
-   * A return value of `null` indicates that the resource can be requested
-   * through another mean than by doing an HTTP request.
-   *
-   * A return value of `undefined` indicates that there's no CDN left to request
-   * the resource.
-   * @returns {Object|null|undefined}
-   */
-  function getCdnToRequest() : ICdnMetadata | null | undefined {
-    if (cdns === null) {
-      const nullAttemptObject = missedAttempts.get(null);
-      if (nullAttemptObject !== undefined && nullAttemptObject.isBlacklisted) {
-        return undefined;
-      }
-      return null;
-    } else if (cdnPrioritizer === null) {
-      return getPrioritaryRequestableCdnFromSortedList(cdns);
-    } else {
-      const prioritized = cdnPrioritizer.getCdnPreferenceForResource(cdns);
-      return getPrioritaryRequestableCdnFromSortedList(prioritized);
-    }
-  }
-
-  /**
-   * Perform immediately the request for the given CDN.
-   *
-   * If it fails, forbid the CDN from being used - optionally and in some
-   * conditions, only temporarily, then try the next CDN according to
-   * previously-set delays (with a potential sleep before to respect them).
-   *
-   * Reject if both the request fails and there's no CDN left to use.
-   * @param {string|null} cdn
-   * @returns {Promise}
-   */
-  async function requestCdn(cdn : ICdnMetadata | null) : Promise<T> {
-    try {
-      const res = await performRequest(cdn, cancellationSignal);
-      return res;
-    } catch (error : unknown) {
-      if (TaskCanceller.isCancellationError(error)) {
-        throw error;
-      }
-
-      if (cdn !== null && cdnPrioritizer !== null) {
-        // We failed requesting the resource on this CDN.
-        // Globally give priority to the next CDN through the CdnPrioritizer.
-        cdnPrioritizer.downgradeCdn(cdn);
-      }
-
-      const currentErrorType = getRequestErrorType(error);
-
-      let missedAttemptsObj = missedAttempts.get(cdn);
-      if (missedAttemptsObj === undefined) {
-        missedAttemptsObj = { errorCounter: 1,
-                              lastErrorType: currentErrorType,
-                              blockedUntil: undefined,
-                              isBlacklisted: false };
-        missedAttempts.set(cdn, missedAttemptsObj);
-      } else {
-        if (currentErrorType !== missedAttemptsObj.lastErrorType) {
-          missedAttemptsObj.errorCounter = 1;
-          missedAttemptsObj.lastErrorType = currentErrorType;
-        } else {
-          missedAttemptsObj.errorCounter++;
-        }
-      }
-
-      if (!shouldRetry(error)) {
-        missedAttemptsObj.blockedUntil = undefined;
-        missedAttemptsObj.isBlacklisted = true;
-        return retryWithNextCdn(error);
-      }
-
-      const maxRetry = currentErrorType === REQUEST_ERROR_TYPES.Offline ?
-        maxRetryOffline :
-        maxRetryRegular;
-
-      if (missedAttemptsObj.errorCounter > maxRetry) {
-        missedAttemptsObj.blockedUntil = undefined;
-        missedAttemptsObj.isBlacklisted = true;
-      } else {
-        const errorCounter = missedAttemptsObj.errorCounter;
-        const delay = Math.min(baseDelay * Math.pow(2, errorCounter - 1),
-                               maxDelay);
-        const fuzzedDelay = getFuzzedDelay(delay);
-        missedAttemptsObj.blockedUntil = performance.now() + fuzzedDelay;
-      }
-
-      return retryWithNextCdn(error);
-    }
-  }
-
-  /**
-   * After a request error, find the new most prioritary CDN and perform the
-   * request with it, optionally after a delay.
-   *
-   * If there's no CDN left to test, reject the original request error.
-   * @param {*} prevRequestError
-   * @returns {Promise}
-   */
-  async function retryWithNextCdn(prevRequestError : unknown) : Promise<T> {
-    const nextCdn = getCdnToRequest();
-
-    if (cancellationSignal.isCancelled()) {
-      throw cancellationSignal.cancellationError;
-    }
-
-    if (nextCdn === undefined) {
-      throw prevRequestError;
-    }
-
-    onRetry(prevRequestError);
-    if (cancellationSignal.isCancelled()) {
-      throw cancellationSignal.cancellationError;
-    }
-
-    return waitPotentialBackoffAndRequest(nextCdn, prevRequestError);
-  }
-
-  /**
-   * Request the corresponding CDN after the optional backoff needed before
-   * requesting it.
-   *
-   * If a new CDN become prioritary in the meantime, request it instead, again
-   * awaiting its optional backoff delay if it exists.
-   * @param {string|null} nextWantedCdn
-   * @param {*} prevRequestError
-   * @returns {Promise}
-   */
-  function waitPotentialBackoffAndRequest(
-    nextWantedCdn: ICdnMetadata | null,
-    prevRequestError : unknown
-  ) : Promise<T> {
-    const nextCdnAttemptObj = missedAttempts.get(nextWantedCdn);
-    if (nextCdnAttemptObj === undefined ||
-        nextCdnAttemptObj.blockedUntil === undefined)
-    {
-      return requestCdn(nextWantedCdn);
-    }
-
-    const now = performance.now();
-    const blockedFor = nextCdnAttemptObj.blockedUntil - now;
-    if (blockedFor <= 0) {
-      return requestCdn(nextWantedCdn);
-    }
-
-    const canceller = new TaskCanceller();
-    const unlinkCanceller = canceller.linkToSignal(cancellationSignal);
-    return new Promise<T>((res, rej) => {
-      /* eslint-disable-next-line @typescript-eslint/no-misused-promises */
-      cdnPrioritizer?.addEventListener("priorityChange", () => {
-        const updatedPrioritaryCdn = getCdnToRequest();
-        if (cancellationSignal.isCancelled()) {
-          throw cancellationSignal.cancellationError;
-        }
-        if (updatedPrioritaryCdn === undefined) {
-          return cleanAndReject(prevRequestError);
-        }
-        if (updatedPrioritaryCdn !== nextWantedCdn) {
-          canceller.cancel();
-          waitPotentialBackoffAndRequest(updatedPrioritaryCdn, prevRequestError)
-            .then(cleanAndResolve, cleanAndReject);
-        }
-      }, canceller.signal);
-
-      cancellableSleep(blockedFor, canceller.signal)
-        .then(() => requestCdn(nextWantedCdn)
-          .then(cleanAndResolve, cleanAndReject), noop);
-
-      function cleanAndResolve(response : T) {
-        unlinkCanceller();
-        res(response);
-      }
-      function cleanAndReject(err : unknown) {
-        unlinkCanceller();
-        rej(err);
-      }
-    });
-  }
-
-  /**
-   * Takes in input the list of CDN that can be used to request the resource, in
-   * a general preference order.
-   *
-   * Returns the actual most prioritary Cdn to request, based on the current
-   * attempts already done for that resource.
-   *
-   * Returns `undefined` if there's no Cdn left to request the resource.
-   * @param {Array.<Object>}
-   * @returns {Object|undefined}
-   */
-  function getPrioritaryRequestableCdnFromSortedList(
-    sortedCdns : ICdnMetadata[]
-  ) : ICdnMetadata | undefined {
-    if (missedAttempts.size === 0) {
-      return sortedCdns[0];
-    }
-    const now = performance.now();
-    return sortedCdns
-      .filter(c =>  missedAttempts.get(c)?.isBlacklisted !== true)
-      .reduce((
-        acc : [ICdnMetadata, number | undefined] | undefined,
-        x : ICdnMetadata
-      ) : [ICdnMetadata, number | undefined] => {
-        let blockedUntil = missedAttempts.get(x)?.blockedUntil;
-        if (blockedUntil !== undefined && blockedUntil <= now) {
-          blockedUntil = undefined;
-        }
-        if (acc === undefined) {
-          return [x, blockedUntil];
-        }
-        if (blockedUntil === undefined) {
-          if (acc[1] === undefined) {
-            return acc;
-          }
-          return [x, undefined];
-        }
-
-        return acc[1] === undefined  ? acc :
-          blockedUntil < acc[1] ? [x, blockedUntil] :
-          acc;
-      }, undefined)?.[0];
-  }
-}
-
-/**
- * Lightweight version of the request algorithm, this time with only a simple
- * Promise given.
- * @param {Function} performRequest
- * @param {Object} options
- * @returns {Promise}
- */
-export function scheduleRequestPromise<T>(
-  performRequest : () => Promise<T>,
-  options : IBackoffSettings,
-  cancellationSignal : CancellationSignal
-) : Promise<T> {
-  // same than for a single unknown CDN
-  return scheduleRequestWithCdns(null,
-                                 null,
-                                 performRequest,
-                                 options,
-                                 cancellationSignal);
-}
-
-/**
- * Metadata associated to attempt(s) of requesting a resource through the same
- * CDN.
- *
- * Each `ICdnAttemptMetadata` object should concern only one CDN.
- */
-interface ICdnAttemptMetadata {
-  /**
-   * Count the amount of consecutive times an error of type `lastErrorType` has
-   * been encountered while requesting this resource though the concerned CDN.
-   *
-   * For example `1` means that the request through this CDN either failed for
-   * the first consecutive time or that it already failed just before but for an
-   * error with a different `lastErrorType` value.
-   * `2` means that after requesting this CDN two consecutive times, the request
-   * failed with an error with the same `lastErrorType` value.
-   * etc.
-   */
-  errorCounter : number;
-  /** The last type of error encountered when requesting through that CDN. */
-  lastErrorType : REQUEST_ERROR_TYPES;
-  /**
-   * Timestamp, in terms of `performance.now()`, until which it should be
-   * forbidden to request this CDN.
-   * Enforcing this delay allows to prevent making too much requests to a given
-   * CDN.
-   *
-   * `undefined` when either there is no enforced delay or when the CDN is
-   * blacklisted anyway (@see isBlacklisted)
-   */
-  blockedUntil : number | undefined;
-  /** If `true`, that request should not be requested at all anymore. */
-  isBlacklisted : boolean;
-}

package/src/core/init/README.md

@@ -1,81 +0,0 @@
-# The `ContentInitializer` #####################################################
-
-The ContentInitializer is the part of the code actually starting and running the
-logic behind playing a content.
-
-Its code is written in the `src/core/init` directory.
-
-Every time you're calling the API to load a new video, a ContentInitializer is
-called by it (with multiple options).
-
-The ContentInitializer then starts loading the content and communicate back its progress to
-the API through events.
-
-```
-                 +-----------+
- 1. loadVideo    |           |      2. Instanciate
----------------> |    API    | -------------------+
-                 |           |                    |
-                 +-----------+                    |
-                       ^                          v
-                       |                    +--------------------+
-                       |   3. Emit events   |                    |
-                       +------------------- | ContentInitializer |
-                                            |                    |
-                                            +--------------------+
-```
-During the various events happening on content playback, the ContentInitializer will
-create / destroy / update various player submodules.
-
-Example of such submodules are:
-  - Adaptive streaming management
-  - DRM handling
-  - Manifest loading, parsing and refreshing
-  - Buffer management
-  - ...
-
-
-
-## Usage #######################################################################
-
-Concretely, the ContentInitializer is a class respecting a given interface,
-allowing to:
-
-  - prepare a future content for future play - without influencing a potentially
-    already-playing content (e.g. by pre-loading the next content's Manifest).
-
-  - start loading the content on a given media element
-
-  - communicate about various playback events
-
-
-### Emitted Events #############################################################
-
-Events allows the ContentInitializer to reports milestones of the content
-playback, such as when the content is ready to play.
-
-It's also a way for the `ContentInitializer` to communicate information about
-the content and give some controls to the user.
-
-For example, as available audio languages are only known after the manifest has
-been downloaded and parsed, and as it is most of all a user preference, the
-ContentInitializer can emit to the API, objects allowing the API to "choose" at
-any time the wanted language.
-
-
-
-### Playback rate management ###################################################
-
-The playback rate (or speed) is updated by the ContentInitializer.
-
-There can be three occasions for these updates:
-
-  - the API set a new speed
-
-  - the content needs to build its buffer.
-
-    In which case, the playback speed will be set to 0 (paused) even if the
-    API set another speed.
-
-  - the content has built enough buffer to un-pause.
-    The regular speed set by the user will be set again in that case.