/** * Copyright 2016, Google Inc. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: * * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following disclaimer * in the documentation and/or other materials provided with the * distribution. * * Neither the name of Google Inc. nor the names of its * contributors may be used to endorse or promote products derived from * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ import { BundleOptions } from './bundling'; /** * Encapsulates the overridable settings for a particular API call. * * ``CallOptions`` is an optional arg for all GAX API calls. It is used to * configure the settings of a specific API call. * * When provided, its values override the GAX service defaults for that * particular call. * * Typically the API clients will accept this as the second to the last * argument. See the examples below. * @typedef {Object} CallOptions * @property {number=} timeout - The client-side timeout for API calls. * @property {RetryOptions=} retry - determines whether and how to retry * on transient errors. When set to null, the call will not retry. * @property {boolean=} autoPaginate - If set to false and the call is * configured for paged iteration, page unrolling is not performed, instead * the callback will be called with the response object. * @property {Object=} pageToken - If set and the call is configured for * paged iteration, paged iteration is not performed and requested with this * pageToken. * @property {number} maxResults - If set and the call is configured for * paged iteration, the call will stop when the number of response elements * reaches to the specified size. By default, it will unroll the page to * the end of the list. * @property {boolean=} isBundling - If set to false and the call is configured * for bundling, bundling is not performed. * @property {BackoffSettings=} longrunning - BackoffSettings used for polling. * @property {Function=} promise - A constructor for a promise that implements the ES6 * specification of promise which will be used to create promises. If not * provided, native promises will be used. * @example * // suppress bundling for bundled method. * api.bundlingMethod( * param, {optParam: aValue, isBundling: false}, function(err, response) { * // handle response. * }); * @example * // suppress streaming for page-streaming method. * api.pageStreamingMethod( * param, {optParam: aValue, autoPaginate: false}, function(err, page) { * // not returning a stream, but callback is called with the paged response. * }); */ /** * Per-call configurable settings for retrying upon transient failure. * @typedef {Object} RetryOptions * @property {String[]} retryCodes * @property {BackoffSettings} backoffSettings */ export declare class RetryOptions { retryCodes: number[]; backoffSettings: BackoffSettings; constructor(retryCodes: number[], backoffSettings: BackoffSettings); } /** * Parameters to the exponential backoff algorithm for retrying. * @typedef {Object} BackoffSettings * @property {number} initialRetryDelayMillis - the initial delay time, * in milliseconds, between the completion of the first failed request and the * initiation of the first retrying request. * @property {number} retryDelayMultiplier - the multiplier by which to * increase the delay time between the completion of failed requests, and the * initiation of the subsequent retrying request. * @property {number} maxRetryDelayMillis - the maximum delay time, in * milliseconds, between requests. When this value is reached, * ``retryDelayMultiplier`` will no longer be used to increase delay time. * @property {number} initialRpcTimeoutMillis - the initial timeout parameter * to the request. * @propetry {number} rpcTimeoutMultiplier - the multiplier by which to * increase the timeout parameter between failed requests. * @property {number} maxRpcTimeoutMillis - the maximum timeout parameter, in * milliseconds, for a request. When this value is reached, * ``rpcTimeoutMultiplier`` will no longer be used to increase the timeout. * @property {number} totalTimeoutMillis - the total time, in milliseconds, * starting from when the initial request is sent, after which an error will * be returned, regardless of the retrying attempts made meanwhile. */ export interface BackoffSettings { maxRetries?: number; initialRetryDelayMillis: number; retryDelayMultiplier: number; maxRetryDelayMillis: number; initialRpcTimeoutMillis: number | null; maxRpcTimeoutMillis: number | null; totalTimeoutMillis: number | null; rpcTimeoutMultiplier: number | null; } /** * Parameter to configure bundling behavior. * @typedef {Object} BundleOptions * @property {number} elementCountThreshold - * the bundled request will be sent once the count of outstanding elements * in the repeated field reaches this value. * @property {number} elementCountLimit - * represents a hard limit on the number of elements in the repeated field * of the bundle; if adding a request to a bundle would exceed this value, * the bundle is sent and the new request is added to a fresh bundle. It is * invalid for a single request to exceed this limit. * @property {number} requestByteThreshold - * the bundled request will be sent once the count of bytes in the request * reaches this value. Note that this value is pessimistically approximated * by summing the bytesizes of the elements in the repeated field, and * therefore may be an under-approximation. * @property {number} requestByteLimit - * represents a hard limit on the size of the bundled request; if adding * a request to a bundle would exceed this value, the bundle is sent and * the new request is added to a fresh bundle. It is invalid for a single * request to exceed this limit. Note that this value is pessimistically * approximated by summing the bytesizes of the elements in the repeated * field, with a buffer applied to correspond to the resulting * under-approximation. * @property {number} delayThreshold - * the bundled request will be sent this amount of time after the first * element in the bundle was added to it. */ export interface CallOptions { timeout?: number; retry?: RetryOptions | null; autoPaginate?: boolean; pageToken?: number; maxResults?: number; maxRetries?: number; otherArgs?: { [index: string]: any; }; bundleOptions?: BundleOptions | null; isBundling?: boolean; longrunning?: boolean | null; promise?: PromiseConstructor; } export declare class CallSettings { timeout: number; retry?: RetryOptions | null; autoPaginate?: boolean; pageToken?: number; maxResults?: number; otherArgs: { [index: string]: any; }; bundleOptions?: BundleOptions | null; isBundling: boolean; longrunning?: boolean | null; promise: PromiseConstructor; /** * @param {Object} settings - An object containing parameters of this settings. * @param {number} settings.timeout - The client-side timeout for API calls. * This parameter is ignored for retrying calls. * @param {RetryOptions} settings.retry - The configuration for retrying upon * transient error. If set to null, this call will not retry. * @param {boolean} settings.autoPaginate - If there is no `pageDescriptor`, * this attrbute has no meaning. Otherwise, determines whether a page * streamed response should make the page structure transparent to the user by * flattening the repeated field in the returned generator. * @param {number} settings.pageToken - If there is no `pageDescriptor`, * this attribute has no meaning. Otherwise, determines the page token used * in the page streaming request. * @param {Object} settings.otherArgs - Additional arguments to be passed to * the API calls. * @param {Function=} settings.promise - A constructor for a promise that * implements the ES6 specification of promise. If not provided, native * promises will be used. * * @constructor */ constructor(settings?: CallOptions); /** * Returns a new CallSettings merged from this and a CallOptions object. * * @param {CallOptions} options - an instance whose values override * those in this object. If null, ``merge`` returns a copy of this * object * @return {CallSettings} The merged CallSettings instance. */ merge(options?: CallOptions | null): CallSettings; } /** * Per-call configurable settings for retrying upon transient failure. * * @param {String[]} retryCodes - a list of Google API canonical error codes * upon which a retry should be attempted. * @param {BackoffSettings} backoffSettings - configures the retry * exponential backoff algorithm. * @return {RetryOptions} A new RetryOptions object. * */ export declare function createRetryOptions(retryCodes: number[], backoffSettings: BackoffSettings): RetryOptions; /** * Parameters to the exponential backoff algorithm for retrying. * * @param {number} initialRetryDelayMillis - the initial delay time, * in milliseconds, between the completion of the first failed request and the * initiation of the first retrying request. * @param {number} retryDelayMultiplier - the multiplier by which to * increase the delay time between the completion of failed requests, and the * initiation of the subsequent retrying request. * @param {number} maxRetryDelayMillis - the maximum delay time, in * milliseconds, between requests. When this value is reached, * ``retryDelayMultiplier`` will no longer be used to increase delay time. * @param {number} initialRpcTimeoutMillis - the initial timeout parameter * to the request. * @param {number} rpcTimeoutMultiplier - the multiplier by which to * increase the timeout parameter between failed requests. * @param {number} maxRpcTimeoutMillis - the maximum timeout parameter, in * milliseconds, for a request. When this value is reached, * ``rpcTimeoutMultiplier`` will no longer be used to increase the timeout. * @param {number} totalTimeoutMillis - the total time, in milliseconds, * starting from when the initial request is sent, after which an error will * be returned, regardless of the retrying attempts made meanwhile. * @return {BackoffSettings} a new settings. * */ export declare function createBackoffSettings(initialRetryDelayMillis: number, retryDelayMultiplier: number, maxRetryDelayMillis: number, initialRpcTimeoutMillis: number | null, rpcTimeoutMultiplier: number | null, maxRpcTimeoutMillis: number | null, totalTimeoutMillis: number | null): BackoffSettings; /** * Parameters to the exponential backoff algorithm for retrying. * This function is unsupported, and intended for internal use only. * * @param {number} initialRetryDelayMillis - the initial delay time, * in milliseconds, between the completion of the first failed request and the * initiation of the first retrying request. * @param {number} retryDelayMultiplier - the multiplier by which to * increase the delay time between the completion of failed requests, and the * initiation of the subsequent retrying request. * @param {number} maxRetryDelayMillis - the maximum delay time, in * milliseconds, between requests. When this value is reached, * ``retryDelayMultiplier`` will no longer be used to increase delay time. * @param {number} initialRpcTimeoutMillis - the initial timeout parameter * to the request. * @param {number} rpcTimeoutMultiplier - the multiplier by which to * increase the timeout parameter between failed requests. * @param {number} maxRpcTimeoutMillis - the maximum timeout parameter, in * milliseconds, for a request. When this value is reached, * ``rpcTimeoutMultiplier`` will no longer be used to increase the timeout. * @param {number} maxRetries - the maximum number of retrying attempts that * will be made. If reached, an error will be returned. * @return {BackoffSettings} a new settings. * */ export declare function createMaxRetriesBackoffSettings(initialRetryDelayMillis: number, retryDelayMultiplier: number, maxRetryDelayMillis: number, initialRpcTimeoutMillis: number, rpcTimeoutMultiplier: number, maxRpcTimeoutMillis: number, maxRetries: number): { initialRetryDelayMillis: number; retryDelayMultiplier: number; maxRetryDelayMillis: number; initialRpcTimeoutMillis: number; rpcTimeoutMultiplier: number; maxRpcTimeoutMillis: number; maxRetries: number; }; /** * Creates a new {@link BundleOptions}. * * @private * @param {Object} options - An object to hold optional parameters. See * properties for the content of options. * @return {BundleOptions} - A new options. */ export declare function createBundleOptions(options: BundlingConfig): BundleOptions; export interface ServiceConfig { retry_codes: { [index: string]: string[]; }; retry_params: { [index: string]: RetryParamsConfig; }; methods: { [index: string]: MethodConfig; }; } export interface RetryParamsConfig { initial_retry_delay_millis: number; retry_delay_multiplier: number; max_retry_delay_millis: number; initial_rpc_timeout_millis: number; rpc_timeout_multiplier: number; max_rpc_timeout_millis: number; total_timeout_millis: number; } export interface MethodConfig { retry_codes_name: string; retry_params_name: string; bundling: BundlingConfig; timeout_millis?: number; } export interface BundlingConfig { [index: string]: number; element_count_threshold: number; element_count_limit: number; request_byte_threshold: number; request_byte_limit: number; delay_threshold_millis: number; } export interface ClientConfig { interfaces?: { [index: string]: ServiceConfig; }; } /** * Constructs a dictionary mapping method names to {@link CallSettings}. * * The `clientConfig` parameter is parsed from a client configuration JSON * file of the form: * * { * "interfaces": { * "google.fake.v1.ServiceName": { * "retry_codes": { * "idempotent": ["UNAVAILABLE", "DEADLINE_EXCEEDED"], * "non_idempotent": [] * }, * "retry_params": { * "default": { * "initial_retry_delay_millis": 100, * "retry_delay_multiplier": 1.2, * "max_retry_delay_millis": 1000, * "initial_rpc_timeout_millis": 2000, * "rpc_timeout_multiplier": 1.5, * "max_rpc_timeout_millis": 30000, * "total_timeout_millis": 45000 * } * }, * "methods": { * "CreateFoo": { * "retry_codes_name": "idempotent", * "retry_params_name": "default" * }, * "Publish": { * "retry_codes_name": "non_idempotent", * "retry_params_name": "default", * "bundling": { * "element_count_threshold": 40, * "element_count_limit": 200, * "request_byte_threshold": 90000, * "request_byte_limit": 100000, * "delay_threshold_millis": 100 * } * } * } * } * } * } * * @param {String} serviceName - The fully-qualified name of this * service, used as a key into the client config file (in the * example above, this value should be 'google.fake.v1.ServiceName'). * @param {Object} clientConfig - A dictionary parsed from the * standard API client config file. * @param {Object} configOverrides - A dictionary in the same structure of * client_config to override the settings. * @param {Object.} retryNames - A dictionary mapping the strings * referring to response status codes to objects representing * those codes. * @param {Object} otherArgs - the non-request arguments to be passed to the API * calls. * @param {Function=} promise - A constructor for a promise that implements the * ES6 specification of promise. If not provided, native promises will be used. * @return {Object} A mapping from method name to CallSettings, or null if the * service is not found in the config. */ export declare function constructSettings(serviceName: string, clientConfig: ClientConfig, configOverrides: ClientConfig, retryNames: { [index: string]: number; }, otherArgs?: {}, promise?: PromiseConstructor): any;