Source: lib/offline/storage_muxer.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.offline.StorageCellHandle');
  8. goog.provide('shaka.offline.StorageCellPath');
  9. goog.provide('shaka.offline.StorageMuxer');
  11. goog.require('shaka.log');
  12. goog.require('shaka.util.Error');
  13. goog.require('shaka.util.IDestroyable');
  15. /**
  16.  * @typedef {{
  17.  *  mechanism: string,
  18.  *  cell: string
  19.  * }}
  20.  *
  21.  * @property {string} mechanism
  22.  *  The name of the mechanism that holds the cell.
  23.  * @property {string} cell
  24.  *  The name of the cell in the mechanism.
  25.  */
  26. shaka.offline.StorageCellPath;
  29. /**
  30.  * @typedef {{
  31.  *   path: shaka.offline.StorageCellPath,
  32.  *   cell: !shaka.extern.StorageCell
  33.  * }}
  34.  *
  35.  * @property {shaka.offline.StorageCellPath} path
  36.  *   The path that maps to the cell.
  37.  * @property {shaka.extern.StorageCell} cell
  38.  *   The storage cell that the path points to within the storage muxer.
  39.  */
  40. shaka.offline.StorageCellHandle;
  43. // TODO: revisit this when Closure Compiler supports partially-exported classes.
  44. /**
  45.  * StorageMuxer is responsible for managing StorageMechanisms and addressing
  46.  * cells. The primary purpose of the muxer is to give the caller the correct
  47.  * cell for the operations they want to perform.
  48.  *
  49.  * |findActive| will be used when the caller wants a cell that supports
  50.  * add-operations. This will be used when saving new content to storage.
  51.  *
  52.  * |findAll| will be used when the caller want to look at all the content
  53.  * in storage.
  54.  *
  55.  * |resolvePath| will be used to convert a path (from |findActive| and
  56.  * |findAll|) into a cell, which it then returns.
  57.  *
  58.  * @implements {shaka.util.IDestroyable}
  59.  * @export
  60.  */
  61. shaka.offline.StorageMuxer = class {
  62.   /** */
  63.   constructor() {
  64.     /**
  65.      * A key in this map is the name given when registering a StorageMechanism.
  66.      *
  67.      * @private {!Map<string, !shaka.extern.StorageMechanism>}
  68.      */
  69.     this.mechanisms_ = new Map();
  70.   }
  72.   // TODO: revisit this when the compiler supports partially-exported classes.
  73.   /**
  74.    * Free all resources used by the muxer, mechanisms, and cells. This should
  75.    * not affect the stored content.
  76.    *
  77.    * @override
  78.    * @export
  79.    */
  80.   destroy() {
  81.     /** @type {!Array<!Promise>} */
  82.     const destroys = [];
  83.     for (const mechanism of this.mechanisms_.values()) {
  84.       destroys.push(mechanism.destroy());
  85.     }
  87.     // Empty the map so that subsequent calls will be no-ops.
  88.     this.mechanisms_.clear();
  90.     return Promise.all(destroys);
  91.   }
  93.   /**
  94.    * Initialize the storage muxer. This must be called before any other calls.
  95.    * This will initialize the muxer to use all mechanisms that have been
  96.    * registered with |StorageMuxer.register|.
  97.    *
  98.    * @return {!Promise}
  99.    */
  100.   init() {
  101.     // Add the new instance of each mechanism to the muxer.
  102.     const registry = shaka.offline.StorageMuxer.getRegistry_();
  103.     registry.forEach((factory, name) => {
  104.       const mech = factory();
  105.       if (mech) {
  106.         this.mechanisms_.set(name, mech);
  107.       } else {
  108.         shaka.log.info(
  109.             'Skipping ' + name + ' as it is not supported on this platform');
  110.       }
  111.     });
  113.     /** @type {!Array<!Promise>} */
  114.     const initPromises = [];
  115.     for (const mechanism of this.mechanisms_.values()) {
  116.       initPromises.push(mechanism.init());
  117.     }
  119.     return Promise.all(initPromises);
  120.   }
  122.   /**
  123.    * Get a promise that will resolve with a storage cell that supports
  124.    * add-operations. If no cell can be found, the promise will be rejected.
  125.    *
  126.    * @return {shaka.offline.StorageCellHandle}
  127.    */
  128.   getActive() {
  129.     /** @type {?shaka.offline.StorageCellHandle} */
  130.     let handle = null;
  132.     this.mechanisms_.forEach((mechanism, mechanismName) => {
  133.       mechanism.getCells().forEach((cell, cellName) => {
  134.         // If this cell is not useful to us or we already have a handle, then
  135.         // we don't need to make a new handle.
  136.         if (cell.hasFixedKeySpace() || handle) {
  137.           return;
  138.         }
  140.         const path = {
  141.           mechanism: mechanismName,
  142.           cell: cellName,
  143.         };
  145.         handle = {
  146.           path: path,
  147.           cell: cell,
  148.         };
  149.       });
  150.     });
  152.     if (handle) {
  153.       return /** @type {shaka.offline.StorageCellHandle} */(handle);
  154.     }
  156.     throw new shaka.util.Error(
  157.         shaka.util.Error.Severity.CRITICAL,
  158.         shaka.util.Error.Category.STORAGE,
  159.         shaka.util.Error.Code.MISSING_STORAGE_CELL,
  160.         'Could not find a cell that supports add-operations');
  161.   }
  163.   /**
  164.    * @param {function(!shaka.offline.StorageCellPath,
  165.    *                  !shaka.extern.StorageCell)} callback
  166.    */
  167.   forEachCell(callback) {
  168.     this.mechanisms_.forEach((mechanism, mechanismName) => {
  169.       mechanism.getCells().forEach((cell, cellName) => {
  170.         const path = {
  171.           mechanism: mechanismName,
  172.           cell: cellName,
  173.         };
  175.         callback(path, cell);
  176.       });
  177.     });
  178.   }
  180.   /**
  181.    * Get a specific storage cell. The promise will resolve with the storage
  182.    * cell if it is found. If the storage cell is not found, the promise will
  183.    * be rejected.
  184.    *
  185.    * @param {string} mechanismName
  186.    * @param {string} cellName
  187.    * @return {!shaka.extern.StorageCell}
  188.    */
  189.   getCell(mechanismName, cellName) {
  190.     const mechanism = this.mechanisms_.get(mechanismName);
  191.     if (!mechanism) {
  192.       throw new shaka.util.Error(
  193.           shaka.util.Error.Severity.CRITICAL,
  194.           shaka.util.Error.Category.STORAGE,
  195.           shaka.util.Error.Code.MISSING_STORAGE_CELL,
  196.           'Could not find mechanism with name ' + mechanismName);
  197.     }
  199.     const cell = mechanism.getCells().get(cellName);
  200.     if (!cell) {
  201.       throw new shaka.util.Error(
  202.           shaka.util.Error.Severity.CRITICAL,
  203.           shaka.util.Error.Category.STORAGE,
  204.           shaka.util.Error.Code.MISSING_STORAGE_CELL,
  205.           'Could not find cell with name ' + cellName);
  206.     }
  208.     return cell;
  209.   }
  211.   /**
  212.    * @param {function(!shaka.extern.EmeSessionStorageCell)} callback
  213.    */
  214.   forEachEmeSessionCell(callback) {
  215.     this.mechanisms_.forEach((mechanism, name) => {
  216.       callback(mechanism.getEmeSessionCell());
  217.     });
  218.   }
  220.   /**
  221.    * Gets an arbitrary EME session cell that can be used for storing new session
  222.    * info.
  223.    *
  224.    * @return {!shaka.extern.EmeSessionStorageCell}
  225.    */
  226.   getEmeSessionCell() {
  227.     const mechanisms = Array.from(this.mechanisms_.keys());
  228.     if (!mechanisms.length) {
  229.       throw new shaka.util.Error(
  230.           shaka.util.Error.Severity.CRITICAL,
  231.           shaka.util.Error.Category.STORAGE,
  232.           shaka.util.Error.Code.STORAGE_NOT_SUPPORTED,
  233.           'No supported storage mechanisms found');
  234.     }
  236.     return this.mechanisms_.get(mechanisms[0]).getEmeSessionCell();
  237.   }
  239.   /**
  240.    * Find the cell that the path points to. A path is made up of a mount point
  241.    * and a cell id. If a cell can be found, the cell will be returned. If no
  242.    * cell is found, null will be returned.
  243.    *
  244.    * @param {shaka.offline.StorageCellPath} path
  245.    * @return {shaka.extern.StorageCell}
  246.    */
  247.   resolvePath(path) {
  248.     const mechanism = this.mechanisms_.get(path.mechanism);
  250.     if (!mechanism) {
  251.       return null;
  252.     }
  254.     return mechanism.getCells().get(path.cell);
  255.   }
  257.   /**
  258.    * This will erase all previous content from storage. Using paths obtained
  259.    * before calling |erase| is discouraged, as cells may have changed during a
  260.    * erase.
  261.    *
  262.    * @return {!Promise}
  263.    */
  264.   async erase() {
  265.     // If we have initialized, we will use the existing mechanism instances.
  266.     /** @type {!Array<!shaka.extern.StorageMechanism>} */
  267.     const mechanisms = Array.from(this.mechanisms_.values());
  268.     const alreadyInitialized = mechanisms.length > 0;
  270.     // If we have not initialized, we should still be able to erase.  This is
  271.     // critical to our ability to wipe the DB in case of a version mismatch.
  272.     // If there are no instances, create temporary ones and destroy them later.
  273.     if (!alreadyInitialized) {
  274.       const registry = shaka.offline.StorageMuxer.getRegistry_();
  275.       registry.forEach((factory, name) => {
  276.         const mech = factory();
  277.         if (mech) {
  278.           mechanisms.push(mech);
  279.         }
  280.       });
  281.     }
  283.     // Erase all storage mechanisms.
  284.     await Promise.all(mechanisms.map((m) => m.erase()));
  286.     // If we were erasing temporary instances, destroy them, too.
  287.     if (!alreadyInitialized) {
  288.       await Promise.all(mechanisms.map((m) => m.destroy()));
  289.     }
  290.   }
  292.   /**
  293.    * Register a storage mechanism for use with the default storage muxer. This
  294.    * will have no effect on any storage muxer already in main memory.
  295.    *
  296.    * @param {string} name
  297.    * @param {function():shaka.extern.StorageMechanism} factory
  298.    * @export
  299.    */
  300.   static register(name, factory) {
  301.     shaka.offline.StorageMuxer.registry_.set(name, factory);
  302.   }
  305.   /**
  306.    * Unregister a storage mechanism for use with the default storage muxer. This
  307.    * will have no effect on any storage muxer already in main memory.
  308.    *
  309.    * @param {string} name The name that the storage mechanism was registered
  310.    *                      under.
  311.    * @export
  312.    */
  313.   static unregister(name) {
  314.     shaka.offline.StorageMuxer.registry_.delete(name);
  315.   }
  317.   /**
  318.    * Check if there is support for storage on this platform. It is assumed that
  319.    * if there are any mechanisms registered, it means that storage is supported
  320.    * on this platform. We do not check if the mechanisms have any cells.
  321.    *
  322.    * @return {boolean}
  323.    */
  324.   static support() {
  325.     const registry = shaka.offline.StorageMuxer.getRegistry_();
  326.     // Make sure that we will have SOME mechanisms created by creating a
  327.     // mechanism and immediately destroying it.
  328.     for (const create of registry.values()) {
  329.       const instance = create();
  331.       if (instance) {
  332.         instance.destroy();
  333.         return true;
  334.       }
  335.     }
  337.     return false;
  338.   }
  340.   /**
  341.    * Replace the mechanism map used by the muxer. This should only be used
  342.    * in testing.
  343.    *
  344.    * @param {Map<string, function(): shaka.extern.StorageMechanism>} map
  345.    */
  346.   static overrideSupport(map) {
  347.     shaka.offline.StorageMuxer.override_ = map;
  348.   }
  350.   /**
  351.    * Undo a previous call to |overrideSupport|.
  352.    */
  353.   static clearOverride() {
  354.     shaka.offline.StorageMuxer.override_ = null;
  355.   }
  357.   /**
  358.    * Get the registry. If the support has been disabled, this will always
  359.    * an empty registry. Reading should always be done via |getRegistry_|.
  360.    *
  361.    * @return {!Map<string, function(): shaka.extern.StorageMechanism>}
  362.    * @private
  363.    */
  364.   static getRegistry_() {
  365.     const override = shaka.offline.StorageMuxer.override_;
  366.     const registry = shaka.offline.StorageMuxer.registry_;
  368.     if (COMPILED) {
  369.       return registry;
  370.     } else {
  371.       return override || registry;
  372.     }
  373.   }
  374. };
  377. /**
  378.  * @private {Map<string, function(): shaka.extern.StorageMechanism>}
  379.  */
  380. shaka.offline.StorageMuxer.override_ = null;
  383. /**
  384.  * @private {!Map<string, function(): shaka.extern.StorageMechanism>}
  385.  */
  386. shaka.offline.StorageMuxer.registry_ = new Map();