1 | /**
|
2 | * Copyright 2020 Google LLC
|
3 | *
|
4 | * Licensed under the Apache License, Version 2.0 (the "License");
|
5 | * you may not use this file except in compliance with the License.
|
6 | * You may obtain a copy of the License at
|
7 | *
|
8 | * http://www.apache.org/licenses/LICENSE-2.0
|
9 | *
|
10 | * Unless required by applicable law or agreed to in writing, software
|
11 | * distributed under the License is distributed on an "AS IS" BASIS,
|
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
13 | * See the License for the specific language governing permissions and
|
14 | * limitations under the License.
|
15 | */
|
16 | /// <reference types="node" />
|
17 | import * as grpcProtoLoader from '@grpc/proto-loader';
|
18 | import { GoogleAuth, GoogleAuthOptions } from 'google-auth-library';
|
19 | import * as grpc from '@grpc/grpc-js';
|
20 | import { OutgoingHttpHeaders } from 'http';
|
21 | import * as protobuf from 'protobufjs';
|
22 | import * as gax from './gax';
|
23 | import { ClientOptions } from '@grpc/grpc-js/build/src/client';
|
24 | export interface GrpcClientOptions extends GoogleAuthOptions {
|
25 | auth?: GoogleAuth;
|
26 | grpc?: GrpcModule;
|
27 | }
|
28 | export interface MetadataValue {
|
29 | equals: Function;
|
30 | }
|
31 | export interface Metadata {
|
32 | new (): Metadata;
|
33 | set: (key: {}, value?: {} | null) => void;
|
34 | clone: () => Metadata;
|
35 | value: MetadataValue;
|
36 | get: (key: {}) => {};
|
37 | }
|
38 | export declare type GrpcModule = typeof grpc;
|
39 | export interface ClientStubOptions {
|
40 | protocol?: string;
|
41 | servicePath?: string;
|
42 | port?: number;
|
43 | sslCreds?: grpc.ChannelCredentials;
|
44 | [index: string]: string | number | undefined | {};
|
45 | cert?: string;
|
46 | key?: string;
|
47 | }
|
48 | export declare class ClientStub extends grpc.Client {
|
49 | [name: string]: Function;
|
50 | }
|
51 | export declare class GrpcClient {
|
52 | auth: GoogleAuth;
|
53 | grpc: GrpcModule;
|
54 | grpcVersion: string;
|
55 | fallback: boolean | 'rest' | 'proto';
|
56 | private static protoCache;
|
57 | /**
|
58 | * Key for proto cache map. We are doing our best to make sure we respect
|
59 | * the options, so if the same proto file is loaded with different set of
|
60 | * options, the cache won't be used. Since some of the options are
|
61 | * Functions (e.g. `enums: String` - see below in `loadProto()`),
|
62 | * they will be omitted from the cache key. If the cache breaks anything
|
63 | * for you, use the `ignoreCache` parameter of `loadProto()` to disable it.
|
64 | */
|
65 | private static protoCacheKey;
|
66 | /**
|
67 | * In rare cases users might need to deallocate all memory consumed by loaded protos.
|
68 | * This method will delete the proto cache content.
|
69 | */
|
70 | static clearProtoCache(): void;
|
71 | /**
|
72 | * A class which keeps the context of gRPC and auth for the gRPC.
|
73 | *
|
74 | * @param {Object=} options - The optional parameters. It will be directly
|
75 | * passed to google-auth-library library, so parameters like keyFile or
|
76 | * credentials will be valid.
|
77 | * @param {Object=} options.auth - An instance of google-auth-library.
|
78 | * When specified, this auth instance will be used instead of creating
|
79 | * a new one.
|
80 | * @param {Object=} options.grpc - When specified, this will be used
|
81 | * for the 'grpc' module in this context. By default, it will load the grpc
|
82 | * module in the standard way.
|
83 | * @constructor
|
84 | */
|
85 | constructor(options?: GrpcClientOptions);
|
86 | /**
|
87 | * Creates a gRPC credentials. It asks the auth data if necessary.
|
88 | * @private
|
89 | * @param {Object} opts - options values for configuring credentials.
|
90 | * Object=} opts.sslCreds - when specified, this is used instead
{ |
91 | * of default channel credentials.
|
92 | * Promise} The promise which will be resolved to the gRPC credential.
{ |
93 | */
|
94 | _getCredentials(opts: ClientStubOptions): Promise<grpc.ChannelCredentials>;
|
95 | private static defaultOptions;
|
96 | /**
|
97 | * Loads the gRPC service from the proto file(s) at the given path and with the
|
98 | * given options. Caches the loaded protos so the subsequent loads don't do
|
99 | * any disk reads.
|
100 | * @param filename The path to the proto file(s).
|
101 | * @param options Options for loading the proto file.
|
102 | * @param ignoreCache Defaults to `false`. Set it to `true` if the caching logic
|
103 | * incorrectly decides that the options object is the same, or if you want to
|
104 | * re-read the protos from disk for any other reason.
|
105 | */
|
106 | loadFromProto(filename: string | string[], options: grpcProtoLoader.Options, ignoreCache?: boolean): grpc.GrpcObject;
|
107 | /**
|
108 | * Load gRPC proto service from a filename looking in googleapis common protos
|
109 | * when necessary. Caches the loaded protos so the subsequent loads don't do
|
110 | * any disk reads.
|
111 | * @param {String} protoPath - The directory to search for the protofile.
|
112 | * @param {String|String[]} filename - The filename(s) of the proto(s) to be loaded.
|
113 | * If omitted, protoPath will be treated as a file path to load.
|
114 | * @param ignoreCache Defaults to `false`. Set it to `true` if the caching logic
|
115 | * incorrectly decides that the options object is the same, or if you want to
|
116 | * re-read the protos from disk for any other reason.
|
117 | * @return {Object<string, *>} The gRPC loaded result (the toplevel namespace
|
118 | * object).
|
119 | */
|
120 | loadProto(protoPath: string, filename?: string | string[], ignoreCache?: boolean): grpc.GrpcObject;
|
121 | static _resolveFile(protoPath: string, filename: string): string;
|
122 | loadProtoJSON(json: protobuf.INamespace, ignoreCache?: boolean): grpc.GrpcObject;
|
123 | metadataBuilder(headers: OutgoingHttpHeaders): (abTests?: {} | undefined, moreHeaders?: OutgoingHttpHeaders | undefined) => grpc.Metadata;
|
124 | /**
|
125 | * A wrapper of {@link constructSettings} function under the gRPC context.
|
126 | *
|
127 | * Most of parameters are common among constructSettings, please take a look.
|
128 | * @param {string} serviceName - The fullly-qualified name of the service.
|
129 | * @param {Object} clientConfig - A dictionary of the client config.
|
130 | * @param {Object} configOverrides - A dictionary of overriding configs.
|
131 | * @param {Object} headers - A dictionary of additional HTTP header name to
|
132 | * its value.
|
133 | * @return {Object} A mapping of method names to CallSettings.
|
134 | */
|
135 | constructSettings(serviceName: string, clientConfig: gax.ClientConfig, configOverrides: gax.ClientConfig, headers: OutgoingHttpHeaders): any;
|
136 | /**
|
137 | * Creates a gRPC stub with current gRPC and auth.
|
138 | * @param {function} CreateStub - The constructor function of the stub.
|
139 | * @param {Object} options - The optional arguments to customize
|
140 | * gRPC connection. This options will be passed to the constructor of
|
141 | * gRPC client too.
|
142 | * @param {string} options.servicePath - The name of the server of the service.
|
143 | * @param {number} options.port - The port of the service.
|
144 | * @param {grpcTypes.ClientCredentials=} options.sslCreds - The credentials to be used
|
145 | * to set up gRPC connection.
|
146 | * @param {string} defaultServicePath - The default service path.
|
147 | * @return {Promise} A promise which resolves to a gRPC stub instance.
|
148 | */
|
149 | createStub(CreateStub: typeof ClientStub, options: ClientStubOptions, customServicePath?: boolean): Promise<ClientStub>;
|
150 | /**
|
151 | * Detect mTLS client certificate based on logic described in
|
152 | * https://google.aip.dev/auth/4114.
|
153 | *
|
154 | * @param {object} [options] - The configuration object.
|
155 | * @returns {Promise} Resolves array of strings representing cert and key.
|
156 | */
|
157 | _detectClientCertificate(opts?: ClientOptions): Promise<any[]>;
|
158 | /**
|
159 | * Return service path, taking into account mTLS logic.
|
160 | * See: https://google.aip.dev/auth/4114
|
161 | *
|
162 | * @param {string|undefined} servicePath - The path of the service.
|
163 | * @param {string|undefined} customServicePath - Did the user provide a custom service URL.
|
164 | * @param {boolean} hasCertificate - Was a certificate found.
|
165 | * @returns {string} The DNS address for this service.
|
166 | */
|
167 | _mtlsServicePath(servicePath: string | undefined, customServicePath: boolean | undefined, hasCertificate: boolean): string | undefined;
|
168 | /**
|
169 | * Creates a 'bytelength' function for a given proto message class.
|
170 | *
|
171 | * See {@link BundleDescriptor} about the meaning of the return value.
|
172 | *
|
173 | * @param {function} message - a constructor function that is generated by
|
174 | * protobuf.js. Assumes 'encoder' field in the message.
|
175 | * @return {function(Object):number} - a function to compute the byte length
|
176 | * for an object.
|
177 | */
|
178 | static createByteLengthFunction(message: {
|
179 | encode: (obj: {}) => {
|
180 | finish: () => Array<{}>;
|
181 | };
|
182 | }): (obj: {}) => number;
|
183 | }
|
184 | export declare class GoogleProtoFilesRoot extends protobuf.Root {
|
185 | constructor(...args: Array<{}>);
|
186 | resolvePath(originPath: string, includePath: string): string;
|
187 | static _findIncludePath(originPath: string, includePath: string): string;
|
188 | }
|