/*! @license
* Shaka Player
* Copyright 2016 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @externs
*/
/**
* @typedef {{
* maxAttempts: number,
* baseDelay: number,
* backoffFactor: number,
* fuzzFactor: number,
* timeout: number,
* stallTimeout: number,
* connectionTimeout: number
* }}
*
* @description
* Parameters for retrying requests.
*
* @property {number} maxAttempts
* The maximum number of times the request should be attempted.
* @property {number} baseDelay
* The delay before the first retry, in milliseconds.
* @property {number} backoffFactor
* The multiplier for successive retry delays.
* @property {number} fuzzFactor
* The maximum amount of fuzz to apply to each retry delay.
* For example, 0.5 means "between 50% below and 50% above the retry delay."
* @property {number} timeout
* The request timeout, in milliseconds. Zero means "unlimited".
* <i>Defaults to 30000 milliseconds.</i>
* @property {number} stallTimeout
* The request stall timeout, in milliseconds. Zero means "unlimited".
* <i>Defaults to 5000 milliseconds.</i>
* @property {number} connectionTimeout
* The request connection timeout, in milliseconds. Zero means "unlimited".
* <i>Defaults to 10000 milliseconds.</i>
*
* @tutorial network-and-buffering-config
*
* @exportDoc
*/
shaka.extern.RetryParameters;
/**
* @typedef {{
* uris: !Array.<string>,
* method: string,
* body: ?BufferSource,
* headers: !Object.<string, string>,
* allowCrossSiteCredentials: boolean,
* retryParameters: !shaka.extern.RetryParameters,
* licenseRequestType: ?string,
* sessionId: ?string,
* streamDataCallback: ?function(BufferSource):!Promise
* }}
*
* @description
* Defines a network request. This is passed to one or more request filters
* that may alter the request, then it is passed to a scheme plugin which
* performs the actual operation.
*
* @property {!Array.<string>} uris
* An array of URIs to attempt. They will be tried in the order they are
* given.
* @property {string} method
* The HTTP method to use for the request.
* @property {?BufferSource} body
* The body of the request.
* @property {!Object.<string, string>} headers
* A mapping of headers for the request. e.g.: {'HEADER': 'VALUE'}
* @property {boolean} allowCrossSiteCredentials
* Make requests with credentials. This will allow cookies in cross-site
* requests. See {@link https://bit.ly/CorsCred}.
* @property {!shaka.extern.RetryParameters} retryParameters
* An object used to define how often to make retries.
* @property {?string} licenseRequestType
* If this is a LICENSE request, this field contains the type of license
* request it is (not the type of license). This is the |messageType| field
* of the EME message. For example, this could be 'license-request' or
* 'license-renewal'.
* @property {?string} sessionId
* If this is a LICENSE request, this field contains the session ID of the
* EME session that made the request.
* @property {?function(BufferSource):!Promise} streamDataCallback
* A callback function to handle the chunked data of the ReadableStream.
* @exportDoc
*/
shaka.extern.Request;
/**
* @typedef {{
* uri: string,
* data: BufferSource,
* status: (number|undefined),
* headers: !Object.<string, string>,
* timeMs: (number|undefined),
* fromCache: (boolean|undefined)
* }}
*
* @description
* Defines a response object. This includes the response data and header info.
* This is given back from the scheme plugin. This is passed to a response
* filter before being returned from the request call.
*
* @property {string} uri
* The URI which was loaded. Request filters and server redirects can cause
* this to be different from the original request URIs.
* @property {string} originalUri
* The original URI passed to the browser for networking. This is before any
* redirects, but after request filters are executed.
* @property {BufferSource} data
* The body of the response.
* @property {(number|undefined)} status
* The response HTTP status code.
* @property {!Object.<string, string>} headers
* A map of response headers, if supported by the underlying protocol.
* All keys should be lowercased.
* For HTTP/HTTPS, may not be available cross-origin.
* @property {(number|undefined)} timeMs
* Optional. The time it took to get the response, in milliseconds. If not
* given, NetworkingEngine will calculate it using Date.now.
* @property {(boolean|undefined)} fromCache
* Optional. If true, this response was from a cache and should be ignored
* for bandwidth estimation.
*
* @exportDoc
*/
shaka.extern.Response;
/**
* @typedef {!function(string,
* shaka.extern.Request,
* shaka.net.NetworkingEngine.RequestType,
* shaka.extern.ProgressUpdated,
* shaka.extern.HeadersReceived):
* !shaka.extern.IAbortableOperation.<shaka.extern.Response>}
* @description
* Defines a plugin that handles a specific scheme.
*
* The functions accepts four parameters, uri string, request, request type,
* a progressUpdated function, and a headersReceived function. The
* progressUpdated and headersReceived functions can be ignored by plugins that
* do not have this information, but it will always be provided by
* NetworkingEngine.
*
* @exportDoc
*/
shaka.extern.SchemePlugin;
/**
* @typedef {function(number, number, number)}
*
* @description
* A callback function to handle progress event through networking engine in
* player.
* The first argument is a number for duration in milliseconds, that the request
* took to complete.
* The second argument is the total number of bytes downloaded during that
* time.
* The third argument is the number of bytes remaining to be loaded in a
* segment.
* @exportDoc
*/
shaka.extern.ProgressUpdated;
/**
* @typedef {function(!Object.<string, string>)}
*
* @description
* A callback function to handle headers received events through networking
* engine in player.
* The first argument is the headers object of the response.
*/
shaka.extern.HeadersReceived;
/**
* Defines a filter for requests. This filter takes the request and modifies
* it before it is sent to the scheme plugin.
* A request filter can run asynchronously by returning a promise; in this case,
* the request will not be sent until the promise is resolved.
*
* @typedef {!function(shaka.net.NetworkingEngine.RequestType,
* shaka.extern.Request):
(Promise|undefined)}
* @exportDoc
*/
shaka.extern.RequestFilter;
/**
* Defines a filter for responses. This filter takes the response and modifies
* it before it is returned.
* A response filter can run asynchronously by returning a promise.
*
* @typedef {!function(shaka.net.NetworkingEngine.RequestType,
* shaka.extern.Response):
(Promise|undefined)}
* @exportDoc
*/
shaka.extern.ResponseFilter;