Source: lib/net/backoff.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.Backoff');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.util.PublicPromise');
  25. /**
  26.  * Backoff represents delay and backoff state.  This is used by NetworkingEngine
  27.  * for individual requests and by StreamingEngine to retry streaming failures.
  28.  *
  29.  * @param {shakaExtern.RetryParameters} parameters
  30.  * @param {boolean=} opt_autoReset  If true, start at a "first retry" state and
  31.  *   and auto-reset that state when we reach maxAttempts.
  32.  * @param {?function()=} opt_isCanceled  If provided, the backoff will end the
  33.  *   current attempt early when this callback returns true.
  34.  *
  35.  * @struct
  36.  * @constructor
  37.  */
  38. shaka.net.Backoff = function(parameters, opt_autoReset, opt_isCanceled) {
  39.   // Set defaults as we unpack these, so that individual app-level requests in
  40.   // NetworkingEngine can be missing parameters.
  42.   let defaults = shaka.net.Backoff.defaultRetryParameters();
  44.   /**
  45.    * @const
  46.    * @private {number}
  47.    */
  48.   this.maxAttempts_ = (parameters.maxAttempts == null) ?
  49.       defaults.maxAttempts : parameters.maxAttempts;
  51.   goog.asserts.assert(this.maxAttempts_ >= 1, 'maxAttempts should be >= 1');
  53.   /**
  54.    * @const
  55.    * @private {number}
  56.    */
  57.   this.baseDelay_ = (parameters.baseDelay == null) ?
  58.       defaults.baseDelay : parameters.baseDelay;
  60.   goog.asserts.assert(this.baseDelay_ >= 0, 'baseDelay should be >= 0');
  62.   /**
  63.    * @const
  64.    * @private {number}
  65.    */
  66.   this.fuzzFactor_ = (parameters.fuzzFactor == null) ?
  67.       defaults.fuzzFactor : parameters.fuzzFactor;
  69.   goog.asserts.assert(this.fuzzFactor_ >= 0, 'fuzzFactor should be >= 0');
  71.   /**
  72.    * @const
  73.    * @private {number}
  74.    */
  75.   this.backoffFactor_ = (parameters.backoffFactor == null) ?
  76.       defaults.backoffFactor : parameters.backoffFactor;
  78.   goog.asserts.assert(this.backoffFactor_ >= 0, 'backoffFactor should be >= 0');
  80.   /** @private {number} */
  81.   this.numAttempts_ = 0;
  83.   /** @private {number} */
  84.   this.nextUnfuzzedDelay_ = this.baseDelay_;
  86.   /** @private {boolean} */
  87.   this.autoReset_ = opt_autoReset || false;
  89.   /** @private {?function()} */
  90.   this.isCanceled_ = opt_isCanceled || null;
  92.   if (this.autoReset_) {
  93.     // There is no delay before the first attempt.  In StreamingEngine (the
  94.     // intended user of auto-reset mode), the first attempt was implied, so we
  95.     // reset numAttempts to 1.  Therefore maxAttempts (which includes the first
  96.     // attempt) must be at least 2 for us to see a delay.
  97.     goog.asserts.assert(this.maxAttempts_ >= 2,
  98.         'maxAttempts must be >= 2 for autoReset == true');
  99.     this.numAttempts_ = 1;
  100.   }
  101. };
  104. /**
  105.  * @return {!Promise} Resolves when the caller may make an attempt, possibly
  106.  *   after a delay.  Rejects if no more attempts are allowed.
  107.  */
  108. shaka.net.Backoff.prototype.attempt = function() {
  109.   if (this.numAttempts_ >= this.maxAttempts_) {
  110.     if (this.autoReset_) {
  111.       this.reset_();
  112.     } else {
  113.       return Promise.reject();
  114.     }
  115.   }
  117.   let p = new shaka.util.PublicPromise();
  118.   if (this.numAttempts_) {
  119.     // We've already tried before, so delay the Promise.
  121.     // Fuzz the delay to avoid tons of clients hitting the server at once
  122.     // after it recovers from whatever is causing it to fail.
  123.     let fuzzedDelay =
  124.         shaka.net.Backoff.fuzz_(this.nextUnfuzzedDelay_, this.fuzzFactor_);
  125.     this.cancelableTimeout_(p.resolve, fuzzedDelay);
  127.     // Update delay_ for next time.
  128.     this.nextUnfuzzedDelay_ *= this.backoffFactor_;
  129.   } else {
  130.     goog.asserts.assert(!this.autoReset_, 'Failed to delay with auto-reset!');
  131.     p.resolve();
  132.   }
  134.   this.numAttempts_++;
  135.   return p;
  136. };
  139. /**
  140.  * Gets a copy of the default retry parameters.
  141.  *
  142.  * @return {shakaExtern.RetryParameters}
  143.  */
  144. shaka.net.Backoff.defaultRetryParameters = function() {
  145.   // Use a function rather than a constant member so the calling code can
  146.   // modify the values without affecting other call results.
  147.   return {
  148.     maxAttempts: 2,
  149.     baseDelay: 1000,
  150.     backoffFactor: 2,
  151.     fuzzFactor: 0.5,
  152.     timeout: 0
  153.   };
  154. };
  157. /**
  158.  * Fuzz the input value by +/- fuzzFactor.  For example, a fuzzFactor of 0.5
  159.  * will create a random value that is between 50% and 150% of the input value.
  160.  *
  161.  * @param {number} value
  162.  * @param {number} fuzzFactor
  163.  * @return {number} The fuzzed value
  164.  * @private
  165.  */
  166. shaka.net.Backoff.fuzz_ = function(value, fuzzFactor) {
  167.   // A random number between -1 and +1.
  168.   let negToPosOne = (Math.random() * 2.0) - 1.0;
  170.   // A random number between -fuzzFactor and +fuzzFactor.
  171.   let negToPosFuzzFactor = negToPosOne * fuzzFactor;
  173.   // The original value, fuzzed by +/- fuzzFactor.
  174.   return value * (1.0 + negToPosFuzzFactor);
  175. };
  178. /**
  179.  * Reset state in autoReset mode.
  180.  * @private
  181.  */
  182. shaka.net.Backoff.prototype.reset_ = function() {
  183.   goog.asserts.assert(this.autoReset_, 'Should only be used for auto-reset!');
  184.   this.numAttempts_ = 1;
  185.   this.nextUnfuzzedDelay_ = this.baseDelay_;
  186. };
  189. /**
  190.  * Makes a timeout that cancels with isCanceled_ if this has an isCanceled_.
  191.  *
  192.  * @param {Function} fn The callback to invoke when the timeout expires.
  193.  * @param {number} timeoutMs The timeout in milliseconds.
  194.  * @private
  195.  */
  196. shaka.net.Backoff.prototype.cancelableTimeout_ = function(fn, timeoutMs) {
  197.   if (this.isCanceled_) {
  198.     if (this.isCanceled_() || timeoutMs == 0) {
  199.       fn();
  200.     } else {
  201.       // This will break the timeout into 200 ms intervals, so that isCanceled_
  202.       // will be checked periodically.
  203.       let timeToUse = Math.min(200, timeoutMs);
  204.       shaka.net.Backoff.setTimeout_(function() {
  205.         this.cancelableTimeout_(fn, timeoutMs - timeToUse);
  206.       }.bind(this), timeToUse);
  207.     }
  208.   } else {
  209.     shaka.net.Backoff.setTimeout_(fn, timeoutMs);
  210.   }
  211. };
  214. /**
  215.  * This is here only for testability.  Mocking global setTimeout can lead to
  216.  * unintended interactions with other tests.  So instead, we mock this.
  217.  *
  218.  * @param {Function} fn The callback to invoke when the timeout expires.
  219.  * @param {number} timeoutMs The timeout in milliseconds.
  220.  * @return {number} The timeout ID.
  221.  * @private
  222.  */
  223. shaka.net.Backoff.setTimeout_ = function(fn, timeoutMs) {
  224.   return window.setTimeout(fn, timeoutMs);
  225. };