UNPKG

8.93 kBTypeScriptView Raw
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" />
17import * as grpcProtoLoader from '@grpc/proto-loader';
18import { GoogleAuth, GoogleAuthOptions } from 'google-auth-library';
19import * as grpc from '@grpc/grpc-js';
20import { OutgoingHttpHeaders } from 'http';
21import * as protobuf from 'protobufjs';
22import * as gax from './gax';
23import { ClientOptions } from '@grpc/grpc-js/build/src/client';
24export interface GrpcClientOptions extends GoogleAuthOptions {
25 auth?: GoogleAuth;
26 grpc?: GrpcModule;
27}
28export interface MetadataValue {
29 equals: Function;
30}
31export interface Metadata {
32 new (): Metadata;
33 set: (key: {}, value?: {} | null) => void;
34 clone: () => Metadata;
35 value: MetadataValue;
36 get: (key: {}) => {};
37}
38export declare type GrpcModule = typeof grpc;
39export 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}
48export declare class ClientStub extends grpc.Client {
49 [name: string]: Function;
50}
51export 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 * @param {Object=} opts.sslCreds - when specified, this is used instead
91 * of default channel credentials.
92 * @return {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}
184export 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}