--- /dev/null
+/**
+ * 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.
+ */
+/**
+ * Google API Extensions
+ */
+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 {number[]} 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): BackoffSettings;
+/**
+ * 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.<string, string[]>} 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;
git://repos.xcallymotion.com / motion2.git / blobdiff