shaka-player/externs/shaka/net.js

DASH/EME video player library

/*! @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.
 *   The minimum supported value is 1 (only one request without retries).
 * @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,
 *   drmInfo: ?shaka.extern.DrmInfo,
 *   initData: ?Uint8Array,
 *   initDataType: ?string,
 *   streamDataCallback: ?function(BufferSource):!Promise,
 *   requestStartTime: (?number|undefined),
 *   timeToFirstByte: (?number|undefined),
 *   packetNumber: (?number|undefined),
 *   contentType: (?string|undefined)
 * }}
 *
 * @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 {?shaka.extern.DrmInfo} drmInfo
 *   If this is a LICENSE request, this field contains the DRM info used to
 *   initialize EME.
 * @property {?Uint8Array} initData
 *   If this is a LICENSE request, this field contains the initData info used
 *   to initialize EME.
 * @property {?string} initDataType
 *   If this is a LICENSE request, this field contains the initDataType info
 *   used to initialize EME.
 * @property {?function(BufferSource):!Promise} streamDataCallback
 *   A callback function to handle the chunked data of the ReadableStream.
 * @property {(?number|undefined)} requestStartTime
 *   The time that the request started.
 * @property {(?number|undefined)} timeToFirstByte
 *   The time taken to the first byte.
 * @property {(?number|undefined)} packetNumber
 *   A number representing the order the packet within the request.
 * @property {(?string|undefined)} contentType
 *   Content type (e.g. 'video', 'audio' or 'text', 'image')
 * @exportDoc
 */
shaka.extern.Request;


/**
 * @typedef {{
 *   uri: string,
 *   originalUri: string,
 *   data: BufferSource,
 *   status: (number|undefined),
 *   headers: !Object<string, string>,
 *   timeMs: (number|undefined),
 *   fromCache: (boolean|undefined),
 *   originalRequest: shaka.extern.Request
 * }}
 *
 * @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.
 * @property {shaka.extern.Request} originalRequest
 *   The original request that gave rise to this response.
 *
 * @exportDoc
 */
shaka.extern.Response;


/**
 * @typedef {!function(string,
 *                     shaka.extern.Request,
 *                     shaka.net.NetworkingEngine.RequestType,
 *                     shaka.extern.ProgressUpdated,
 *                     shaka.extern.HeadersReceived,
 *                     shaka.extern.SchemePluginConfig):
 *     !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 {{
 *   minBytesForProgressEvents: (number|undefined)
 * }}
 *
 * @description
 *   Defines configuration object to use by SchemePlugins.
 *
 * @property {(number|undefined)} minBytesForProgressEvents
 *   Defines minimum number of bytes that should be use to emit progress event,
 *   if possible.
 *
 * @exportDoc
 */
shaka.extern.SchemePluginConfig;


/**
 * @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;


/**
 * @typedef {{
 *   type: (shaka.net.NetworkingEngine.AdvancedRequestType|undefined),
 *   stream: (shaka.extern.Stream|undefined),
 *   segment: (shaka.media.SegmentReference|undefined),
 *   isPreload: (boolean|undefined)
 * }}
 *
 * @description
 * Defines contextual data about a request
 *
 * @property {shaka.net.NetworkingEngine.AdvancedRequestType=} type
 *   The advanced type
 * @property {shaka.extern.Stream=} stream
 *   The duration of the segment in seconds
 * @property {shaka.media.SegmentReference=} segment
 *   The request's segment reference
 * @property {boolean=} isPreload
 *   Whether the request came from a preload or a normal load.
 * @exportDoc
 */
shaka.extern.RequestContext;


/**
 * Defines a filter for requests.  This filter takes the request and modifies
 * it before it is sent to the scheme plugin.
 * The RequestType describes the basic type of the request (manifest, segment,
 * etc). The optional RequestContext will be provided where applicable to
 * provide additional information about the request. 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,
 *                     shaka.extern.RequestContext=):
 *           (Promise|undefined)}
 * @exportDoc
 */
shaka.extern.RequestFilter;


/**
 * Defines a filter for responses.  This filter takes the response and modifies
 * it before it is returned.
 * The RequestType describes the basic type of the request (manifest, segment,
 * etc). The optional RequestContext will be provided where applicable to
 * provide additional information about the request. A response filter can run
 * asynchronously by returning a promise.
 *
 * @typedef {!function(shaka.net.NetworkingEngine.RequestType,
 *                     shaka.extern.Response,
 *                     shaka.extern.RequestContext=):
 *            (Promise|undefined)}
 * @exportDoc
 */
shaka.extern.ResponseFilter;