Source: externs/shaka/net.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.  */
  19. /** @externs */
  22. /**
  23.  * @typedef {{
  24.  *   maxAttempts: number,
  25.  *   baseDelay: number,
  26.  *   backoffFactor: number,
  27.  *   fuzzFactor: number,
  28.  *   timeout: number
  29.  * }}
  30.  *
  31.  * @description
  32.  *   Parameters for retrying requests.
  33.  *
  34.  * @property {number} maxAttempts
  35.  *   The maximum number of times the request should be attempted.
  36.  * @property {number} baseDelay
  37.  *   The delay before the first retry, in milliseconds.
  38.  * @property {number} backoffFactor
  39.  *   The multiplier for successive retry delays.
  40.  * @property {number} fuzzFactor
  41.  *   The maximum amount of fuzz to apply to each retry delay.
  42.  *   For example, 0.5 means "between 50% below and 50% above the retry delay."
  43.  * @property {number} timeout
  44.  *   The request timeout, in milliseconds.  Zero means "unlimited".
  45.  *
  46.  * @tutorial network-and-buffering-config
  47.  *
  48.  * @exportDoc
  49.  */
  50. shakaExtern.RetryParameters;
  53. /**
  54.  * @typedef {{
  55.  *   uris: !Array.<string>,
  56.  *   method: string,
  57.  *   body: ArrayBuffer,
  58.  *   headers: !Object.<string, string>,
  59.  *   allowCrossSiteCredentials: boolean,
  60.  *   retryParameters: !shakaExtern.RetryParameters
  61.  * }}
  62.  *
  63.  * @description
  64.  * Defines a network request.  This is passed to one or more request filters
  65.  * that may alter the request, then it is passed to a scheme plugin which
  66.  * performs the actual operation.
  67.  *
  68.  * @property {!Array.<string>} uris
  69.  *   An array of URIs to attempt.  They will be tried in the order they are
  70.  *   given.
  71.  * @property {string} method
  72.  *   The HTTP method to use for the request.
  73.  * @property {ArrayBuffer} body
  74.  *   The body of the request.
  75.  * @property {!Object.<string, string>} headers
  76.  *   A mapping of headers for the request.  e.g.: {'HEADER': 'VALUE'}
  77.  * @property {boolean} allowCrossSiteCredentials
  78.  *   Make requests with credentials.  This will allow cookies in cross-site
  79.  *   requests.  See <a href="http://goo.gl/YBRKPe">http://goo.gl/YBRKPe</a>.
  80.  * @property {!shakaExtern.RetryParameters} retryParameters
  81.  *   An object used to define how often to make retries.
  82.  *
  83.  * @exportDoc
  84.  */
  85. shakaExtern.Request;
  88. /**
  89.  * @typedef {{
  90.  *   uri: string,
  91.  *   data: ArrayBuffer,
  92.  *   headers: !Object.<string, string>,
  93.  *   timeMs: (number|undefined),
  94.  *   fromCache: (boolean|undefined)
  95.  * }}
  96.  *
  97.  * @description
  98.  * Defines a response object.  This includes the response data and header info.
  99.  * This is given back from the scheme plugin.  This is passed to a response
  100.  * filter before being returned from the request call.
  101.  *
  102.  * @property {string} uri
  103.  *   The URI which was loaded.  Request filters and server redirects can cause
  104.  *   this to be different from the original request URIs.
  105.  * @property {ArrayBuffer} data
  106.  *   The body of the response.
  107.  * @property {!Object.<string, string>} headers
  108.  *   A map of response headers, if supported by the underlying protocol.
  109.  *   All keys should be lowercased.
  110.  *   For HTTP/HTTPS, may not be available cross-origin.
  111.  * @property {(number|undefined)} timeMs
  112.  *   Optional.  The time it took to get the response, in miliseconds.  If not
  113.  *   given, NetworkingEngine will calculate it using Date.now.
  114.  * @property {(boolean|undefined)} fromCache
  115.  *   Optional. If true, this response was from a cache and should be ignored
  116.  *   for bandwidth estimation.
  117.  *
  118.  * @exportDoc
  119.  */
  120. shakaExtern.Response;
  123. /**
  124.  * Defines a plugin that handles a specific scheme.
  125.  *
  126.  * @typedef {!function(string,
  127.  *                     shakaExtern.Request,
  128.  *                     shaka.net.NetworkingEngine.RequestType):
  129.  *     !Promise.<shakaExtern.Response>}
  130.  * @exportDoc
  131.  */
  132. shakaExtern.SchemePlugin;
  135. /**
  136.  * Defines a filter for requests.  This filter takes the request and modifies
  137.  * it before it is sent to the scheme plugin.
  138.  * A request filter can run asynchronously by returning a promise; in this case,
  139.  * the request will not be sent until the promise is resolved.
  140.  *
  141.  * @typedef {!function(shaka.net.NetworkingEngine.RequestType,
  142.  *                     shakaExtern.Request):
  143.              (Promise|undefined)}
  144.  * @exportDoc
  145.  */
  146. shakaExtern.RequestFilter;
  149. /**
  150.  * Defines a filter for responses.  This filter takes the response and modifies
  151.  * it before it is returned.
  152.  * A response filter can run asynchronously by returning a promise.
  153.  *
  154.  * @typedef {!function(shaka.net.NetworkingEngine.RequestType,
  155.  *                     shakaExtern.Response):
  156.               (Promise|undefined)}
  157.  * @exportDoc
  158.  */
  159. shakaExtern.ResponseFilter;