Source: lib/net/networking_engine.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.net.NetworkingEngine');
  20. goog.require('goog.Uri');
  21. goog.require('goog.asserts');
  22. goog.require('shaka.log');
  23. goog.require('shaka.net.Backoff');
  24. goog.require('shaka.util.AbortableOperation');
  25. goog.require('shaka.util.ArrayUtils');
  26. goog.require('shaka.util.ConfigUtils');
  27. goog.require('shaka.util.Error');
  28. goog.require('shaka.util.IDestroyable');
  29. goog.require('shaka.util.OperationManager');
  33. /**
  34.  * NetworkingEngine wraps all networking operations.  This accepts plugins that
  35.  * handle the actual request.  A plugin is registered using registerScheme.
  36.  * Each scheme has at most one plugin to handle the request.
  37.  *
  38.  * @param {function(number, number)=} opt_onSegmentDownloaded Called
  39.  *   when a segment is downloaded. Passed the duration, in milliseconds, that
  40.  *   the request took, and the total number of bytes transferred.
  41.  *
  42.  * @struct
  43.  * @constructor
  44.  * @implements {shaka.util.IDestroyable}
  45.  * @export
  46.  */
  47. shaka.net.NetworkingEngine = function(opt_onSegmentDownloaded) {
  48.   /** @private {boolean} */
  49.   this.destroyed_ = false;
  51.   /** @private {!shaka.util.OperationManager} */
  52.   this.operationManager_ = new shaka.util.OperationManager();
  54.   /** @private {!Array.<shakaExtern.RequestFilter>} */
  55.   this.requestFilters_ = [];
  57.   /** @private {!Array.<shakaExtern.ResponseFilter>} */
  58.   this.responseFilters_ = [];
  60.   /** @private {?function(number, number)} */
  61.   this.onSegmentDownloaded_ = opt_onSegmentDownloaded || null;
  62. };
  65. /**
  66.  * Request types.  Allows a filter to decide which requests to read/alter.
  67.  *
  68.  * @enum {number}
  69.  * @export
  70.  */
  71. shaka.net.NetworkingEngine.RequestType = {
  72.   'MANIFEST': 0,
  73.   'SEGMENT': 1,
  74.   'LICENSE': 2,
  75.   'APP': 3
  76. };
  79. /**
  80.  * Priority level for network scheme plugins.
  81.  * If multiple plugins are provided for the same scheme, only the
  82.  * highest-priority one is used.
  83.  *
  84.  * @enum {number}
  85.  * @export
  86.  */
  87. shaka.net.NetworkingEngine.PluginPriority = {
  88.   'FALLBACK': 1,
  89.   'PREFERRED': 2,
  90.   'APPLICATION': 3
  91. };
  94. /**
  95.  * @typedef {{
  96.  *   plugin: shakaExtern.SchemePlugin,
  97.  *   priority: number
  98.  * }}
  99.  * @property {shakaExtern.SchemePlugin} plugin
  100.  *   The associated plugin.
  101.  * @property {number} priority
  102.  *   The plugin's priority.
  103.  */
  104. shaka.net.NetworkingEngine.SchemeObject;
  107. /**
  108.  * Contains the scheme plugins.
  109.  *
  110.  * @private {!Object.<string, shaka.net.NetworkingEngine.SchemeObject>}
  111.  */
  112. shaka.net.NetworkingEngine.schemes_ = {};
  115. /**
  116.  * Registers a scheme plugin.  This plugin will handle all requests with the
  117.  * given scheme.  If a plugin with the same scheme already exists, it is
  118.  * replaced, unless the existing plugin is of higher priority.
  119.  * If no priority is provided, this defaults to the highest priority of
  120.  * APPLICATION.
  121.  *
  122.  * @param {string} scheme
  123.  * @param {shakaExtern.SchemePlugin} plugin
  124.  * @param {number=} opt_priority
  125.  * @export
  126.  */
  127. shaka.net.NetworkingEngine.registerScheme =
  128.     function(scheme, plugin, opt_priority) {
  129.   goog.asserts.assert(opt_priority == undefined || opt_priority > 0,
  130.       'explicit priority must be > 0');
  131.   let priority =
  132.       opt_priority || shaka.net.NetworkingEngine.PluginPriority.APPLICATION;
  133.   let existing = shaka.net.NetworkingEngine.schemes_[scheme];
  134.   if (!existing || priority >= existing.priority) {
  135.     shaka.net.NetworkingEngine.schemes_[scheme] = {
  136.       priority: priority,
  137.       plugin: plugin
  138.     };
  139.   }
  140. };
  143. /**
  144.  * Removes a scheme plugin.
  145.  *
  146.  * @param {string} scheme
  147.  * @export
  148.  */
  149. shaka.net.NetworkingEngine.unregisterScheme = function(scheme) {
  150.   delete shaka.net.NetworkingEngine.schemes_[scheme];
  151. };
  154. /**
  155.  * Registers a new request filter.  All filters are applied in the order they
  156.  * are registered.
  157.  *
  158.  * @param {shakaExtern.RequestFilter} filter
  159.  * @export
  160.  */
  161. shaka.net.NetworkingEngine.prototype.registerRequestFilter = function(filter) {
  162.   this.requestFilters_.push(filter);
  163. };
  166. /**
  167.  * Removes a request filter.
  168.  *
  169.  * @param {shakaExtern.RequestFilter} filter
  170.  * @export
  171.  */
  172. shaka.net.NetworkingEngine.prototype.unregisterRequestFilter =
  173.     function(filter) {
  174.   shaka.util.ArrayUtils.remove(this.requestFilters_, filter);
  175. };
  178. /**
  179.  * Clears all request filters.
  180.  *
  181.  * @export
  182.  */
  183. shaka.net.NetworkingEngine.prototype.clearAllRequestFilters = function() {
  184.   this.requestFilters_ = [];
  185. };
  188. /**
  189.  * Registers a new response filter.  All filters are applied in the order they
  190.  * are registered.
  191.  *
  192.  * @param {shakaExtern.ResponseFilter} filter
  193.  * @export
  194.  */
  195. shaka.net.NetworkingEngine.prototype.registerResponseFilter = function(filter) {
  196.   this.responseFilters_.push(filter);
  197. };
  200. /**
  201.  * Removes a response filter.
  202.  *
  203.  * @param {shakaExtern.ResponseFilter} filter
  204.  * @export
  205.  */
  206. shaka.net.NetworkingEngine.prototype.unregisterResponseFilter =
  207.     function(filter) {
  208.   shaka.util.ArrayUtils.remove(this.responseFilters_, filter);
  209. };
  212. /**
  213.  * Clears all response filters.
  214.  *
  215.  * @export
  216.  */
  217. shaka.net.NetworkingEngine.prototype.clearAllResponseFilters = function() {
  218.   this.responseFilters_ = [];
  219. };
  222. /**
  223.  * Gets a copy of the default retry parameters.
  224.  *
  225.  * @return {shakaExtern.RetryParameters}
  226.  *
  227.  * NOTE: The implementation moved to shaka.net.Backoff to avoid a circular
  228.  * dependency between the two classes.
  229.  */
  230. shaka.net.NetworkingEngine.defaultRetryParameters =
  231.     shaka.net.Backoff.defaultRetryParameters;
  234. /**
  235.  * Makes a simple network request for the given URIs.
  236.  *
  237.  * @param {!Array.<string>} uris
  238.  * @param {shakaExtern.RetryParameters} retryParams
  239.  * @return {shakaExtern.Request}
  240.  */
  241. shaka.net.NetworkingEngine.makeRequest = function(
  242.     uris, retryParams) {
  243.   return {
  244.     uris: uris,
  245.     method: 'GET',
  246.     body: null,
  247.     headers: {},
  248.     allowCrossSiteCredentials: false,
  249.     retryParameters: retryParams
  250.   };
  251. };
  254. /**
  255.  * @override
  256.  * @export
  257.  */
  258. shaka.net.NetworkingEngine.prototype.destroy = function() {
  259.   this.destroyed_ = true;
  260.   this.requestFilters_ = [];
  261.   this.responseFilters_ = [];
  262.   return this.operationManager_.destroy();
  263. };
  266. /**
  267.  * Shims return values from requests to look like Promises, so that callers have
  268.  * time to update to the new operation-based API.
  269.  *
  270.  * @param {!shakaExtern.IAbortableOperation.<shakaExtern.Response>} operation
  271.  * @return {!shakaExtern.IAbortableOperation.<shakaExtern.Response>}
  272.  * @private
  273.  */
  274. shaka.net.NetworkingEngine.shimRequests_ = function(operation) {
  275.   // TODO: remove in v2.5
  276.   operation.then = (onSuccess, onError) => {
  277.     shaka.log.alwaysWarn('The network request interface has changed!  Please ' +
  278.                          'update your application to the new interface, ' +
  279.                          'which allows operations to be aborted.  Support ' +
  280.                          'for the old API will be removed in v2.5.');
  281.     return operation.promise.then(onSuccess, onError);
  282.   };
  283.   operation.catch = (onError) => {
  284.     shaka.log.alwaysWarn('The network request interface has changed!  Please ' +
  285.                          'update your application to the new interface, ' +
  286.                          'which allows operations to be aborted.  Support ' +
  287.                          'for the old API will be removed in v2.5.');
  288.     return operation.promise.catch(onError);
  289.   };
  290.   return operation;
  291. };
  294. /**
  295.  * Makes a network request and returns the resulting data.
  296.  *
  297.  * @param {shaka.net.NetworkingEngine.RequestType} type
  298.  * @param {shakaExtern.Request} request
  299.  * @return {!shakaExtern.IAbortableOperation.<shakaExtern.Response>}
  300.  * @export
  301.  */
  302. shaka.net.NetworkingEngine.prototype.request = function(type, request) {
  303.   let cloneObject = shaka.util.ConfigUtils.cloneObject;
  305.   // Reject all requests made after destroy is called.
  306.   if (this.destroyed_) {
  307.     return shaka.net.NetworkingEngine.shimRequests_(
  308.         shaka.util.AbortableOperation.aborted());
  309.   }
  311.   goog.asserts.assert(request.uris && request.uris.length,
  312.                       'Request without URIs!');
  314.   // If a request comes from outside the library, some parameters may be left
  315.   // undefined.  To make it easier for application developers, we will fill them
  316.   // in with defaults if necessary.
  317.   //
  318.   // We clone retryParameters and uris so that if a filter modifies the request,
  319.   // it doesn't contaminate future requests.
  320.   request.method = request.method || 'GET';
  321.   request.headers = request.headers || {};
  322.   request.retryParameters = request.retryParameters ?
  323.       cloneObject(request.retryParameters) :
  324.       shaka.net.NetworkingEngine.defaultRetryParameters();
  325.   request.uris = cloneObject(request.uris);
  327.   let requestFilterOperation = this.filterRequest_(type, request);
  328.   let requestOperation = requestFilterOperation.chain(
  329.       () => this.makeRequestWithRetry_(type, request));
  330.   let responseFilterOperation = requestOperation.chain(
  331.       (response) => this.filterResponse_(type, response));
  333.   // Keep track of time spent in filters.
  334.   let requestFilterStartTime = Date.now();
  335.   let requestFilterMs = 0;
  336.   requestFilterOperation.promise.then(() => {
  337.     requestFilterMs = Date.now() - requestFilterStartTime;
  338.   }, () => {});  // Silence errors in this fork of the Promise chain.
  340.   let responseFilterStartTime = 0;
  341.   requestOperation.promise.then(() => {
  342.     responseFilterStartTime = Date.now();
  343.   }, () => {});  // Silence errors in this fork of the Promise chain.
  345.   let operation = responseFilterOperation.chain((response) => {
  346.     let responseFilterMs = Date.now() - responseFilterStartTime;
  348.     response.timeMs += requestFilterMs;
  349.     response.timeMs += responseFilterMs;
  351.     if (this.onSegmentDownloaded_ && !response.fromCache &&
  352.         type == shaka.net.NetworkingEngine.RequestType.SEGMENT) {
  353.       this.onSegmentDownloaded_(response.timeMs, response.data.byteLength);
  354.     }
  356.     return response;
  357.   }, (e) => {
  358.     // Any error thrown from elsewhere should be recategorized as CRITICAL here.
  359.     // This is because by the time it gets here, we've exhausted retries.
  360.     if (e) {
  361.       goog.asserts.assert(e instanceof shaka.util.Error, 'Wrong error type');
  362.       e.severity = shaka.util.Error.Severity.CRITICAL;
  363.     }
  365.     throw e;
  366.   });
  368.   // Add the operation to the manager for later cleanup.
  369.   this.operationManager_.manage(operation);
  370.   return shaka.net.NetworkingEngine.shimRequests_(operation);
  371. };
  374. /**
  375.  * @param {shaka.net.NetworkingEngine.RequestType} type
  376.  * @param {shakaExtern.Request} request
  377.  * @return {!shakaExtern.IAbortableOperation.<undefined>}
  378.  * @private
  379.  */
  380. shaka.net.NetworkingEngine.prototype.filterRequest_ = function(type, request) {
  381.   let filterOperation = shaka.util.AbortableOperation.completed(undefined);
  383.   this.requestFilters_.forEach((requestFilter) => {
  384.     // Request filters are run sequentially.
  385.     filterOperation =
  386.         filterOperation.chain(() => requestFilter(type, request));
  387.   });
  389.   // Catch any errors thrown by request filters, and substitute
  390.   // them with a Shaka-native error.
  391.   return filterOperation.chain(undefined, (e) => {
  392.     if (e && e.code == shaka.util.Error.Code.OPERATION_ABORTED) {
  393.       // Don't change anything if the operation was aborted.
  394.       throw e;
  395.     }
  397.     throw new shaka.util.Error(
  398.         shaka.util.Error.Severity.CRITICAL,
  399.         shaka.util.Error.Category.NETWORK,
  400.         shaka.util.Error.Code.REQUEST_FILTER_ERROR, e);
  401.   });
  402. };
  405. /**
  406.  * @param {shaka.net.NetworkingEngine.RequestType} type
  407.  * @param {shakaExtern.Request} request
  408.  * @return {!shakaExtern.IAbortableOperation.<shakaExtern.Response>}
  409.  * @private
  410.  */
  411. shaka.net.NetworkingEngine.prototype.makeRequestWithRetry_ =
  412.     function(type, request) {
  413.   let backoff = new shaka.net.Backoff(
  414.       request.retryParameters, /* autoReset */ false);
  415.   let index = 0;
  416.   return this.send_(type, request, backoff, index, /* lastError */ null);
  417. };
  420. /**
  421.  * Sends the given request to the correct plugin and retry using Backoff.
  422.  *
  423.  * @param {shaka.net.NetworkingEngine.RequestType} type
  424.  * @param {shakaExtern.Request} request
  425.  * @param {!shaka.net.Backoff} backoff
  426.  * @param {number} index
  427.  * @param {?shaka.util.Error} lastError
  428.  * @return {!shakaExtern.IAbortableOperation.<shakaExtern.Response>}
  429.  * @private
  430.  */
  431. shaka.net.NetworkingEngine.prototype.send_ = function(
  432.     type, request, backoff, index, lastError) {
  433.   let uri = new goog.Uri(request.uris[index]);
  434.   let scheme = uri.getScheme();
  436.   if (!scheme) {
  437.     // If there is no scheme, infer one from the location.
  438.     scheme = shaka.net.NetworkingEngine.getLocationProtocol_();
  439.     goog.asserts.assert(scheme[scheme.length - 1] == ':',
  440.                         'location.protocol expected to end with a colon!');
  441.     // Drop the colon.
  442.     scheme = scheme.slice(0, -1);
  444.     // Override the original URI to make the scheme explicit.
  445.     uri.setScheme(scheme);
  446.     request.uris[index] = uri.toString();
  447.   }
  449.   let object = shaka.net.NetworkingEngine.schemes_[scheme];
  450.   let plugin = object ? object.plugin : null;
  451.   if (!plugin) {
  452.     return shaka.util.AbortableOperation.failed(
  453.         new shaka.util.Error(
  454.             shaka.util.Error.Severity.CRITICAL,
  455.             shaka.util.Error.Category.NETWORK,
  456.             shaka.util.Error.Code.UNSUPPORTED_SCHEME,
  457.             uri));
  458.   }
  461.   // Every attempt must have an associated backoff.attempt() call so that the
  462.   // accounting is correct.
  463.   let backoffOperation =
  464.       shaka.util.AbortableOperation.notAbortable(backoff.attempt());
  466.   let startTimeMs;
  467.   let sendOperation = backoffOperation.chain(() => {
  468.     if (this.destroyed_) {
  469.       return shaka.util.AbortableOperation.aborted();
  470.     }
  472.     startTimeMs = Date.now();
  473.     let operation = plugin(request.uris[index], request, type);
  475.     // Backward compatibility with older scheme plugins.
  476.     // TODO: remove in v2.5
  477.     if (operation.promise == undefined) {
  478.       shaka.log.alwaysWarn('The scheme plugin interface has changed!  Please ' +
  479.                            'update your scheme plugins to the new interface ' +
  480.                            'to add support for abort().  Support for the old ' +
  481.                            'plugin interface will be removed in v2.5.');
  483.       // The return was just a promise, so wrap it into an operation.
  484.       let schemePromise = /** @type {!Promise} */(operation);
  485.       operation = shaka.util.AbortableOperation.notAbortable(schemePromise);
  486.     }
  487.     return operation;
  488.   }).chain((response) => {
  489.     if (response.timeMs == undefined) {
  490.       response.timeMs = Date.now() - startTimeMs;
  491.     }
  492.     return response;
  493.   }, (error) => {
  494.     if (error && error.code == shaka.util.Error.Code.OPERATION_ABORTED) {
  495.       // Don't change anything if the operation was aborted.
  496.       throw error;
  497.     }
  499.     if (this.destroyed_) {
  500.       return shaka.util.AbortableOperation.aborted();
  501.     }
  503.     if (error && error.severity == shaka.util.Error.Severity.RECOVERABLE) {
  504.       // Move to the next URI.
  505.       index = (index + 1) % request.uris.length;
  506.       let shakaError = /** @type {shaka.util.Error} */(error);
  507.       return this.send_(type, request, backoff, index, shakaError);
  508.     }
  510.     // The error was not recoverable, so do not try again.
  511.     // Rethrow the error so the Promise chain stays rejected.
  512.     throw error || lastError;
  513.   });
  515.   return sendOperation;
  516. };
  519. /**
  520.  * @param {shaka.net.NetworkingEngine.RequestType} type
  521.  * @param {shakaExtern.Response} response
  522.  * @return {!shakaExtern.IAbortableOperation.<shakaExtern.Response>}
  523.  * @private
  524.  */
  525. shaka.net.NetworkingEngine.prototype.filterResponse_ =
  526.     function(type, response) {
  527.   let filterOperation = shaka.util.AbortableOperation.completed(undefined);
  529.   this.responseFilters_.forEach((responseFilter) => {
  530.     // Response filters are run sequentially.
  531.     filterOperation =
  532.         filterOperation.chain(() => responseFilter(type, response));
  533.   });
  535.   return filterOperation.chain(() => {
  536.     // If successful, return the filtered response.
  537.     return response;
  538.   }, (e) => {
  539.     // Catch any errors thrown by request filters, and substitute
  540.     // them with a Shaka-native error.
  542.     if (e && e.code == shaka.util.Error.Code.OPERATION_ABORTED) {
  543.       // Don't change anything if the operation was aborted.
  544.       throw e;
  545.     }
  547.     // The error is assumed to be critical if the original wasn't a Shaka error.
  548.     let severity = shaka.util.Error.Severity.CRITICAL;
  549.     if (e instanceof shaka.util.Error) {
  550.       severity = e.severity;
  551.     }
  553.     throw new shaka.util.Error(
  554.         severity,
  555.         shaka.util.Error.Category.NETWORK,
  556.         shaka.util.Error.Code.RESPONSE_FILTER_ERROR, e);
  557.   });
  558. };
  561. /**
  562.  * This is here only for testability.  We can't mock location in our tests on
  563.  * all browsers, so instead we mock this.
  564.  *
  565.  * @return {string} The value of location.protocol.
  566.  * @private
  567.  */
  568. shaka.net.NetworkingEngine.getLocationProtocol_ = function() {
  569.   return location.protocol;
  570. };