1 | /*!
|
2 | * Copyright 2014 Google Inc. All Rights Reserved.
|
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 { GoogleAuth } from 'google-auth-library';
|
18 | import * as gax from 'google-gax';
|
19 | import { Schema, SchemaType, ISchema, SchemaView } from './schema';
|
20 | import { Snapshot } from './snapshot';
|
21 | import { Subscription, SubscriptionOptions, CreateSubscriptionOptions, CreateSubscriptionCallback, CreateSubscriptionResponse, DetachSubscriptionCallback, DetachSubscriptionResponse } from './subscription';
|
22 | import { Topic, GetTopicSubscriptionsCallback, GetTopicSubscriptionsResponse, CreateTopicCallback, CreateTopicResponse, TopicMetadata } from './topic';
|
23 | import { PublishOptions } from './publisher';
|
24 | import { CallOptions } from 'google-gax';
|
25 | import { Transform } from 'stream';
|
26 | import { google } from '../protos/protos';
|
27 | import { SchemaServiceClient } from './v1';
|
28 | export declare type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
|
29 | export interface ClientConfig extends gax.GrpcClientOptions {
|
30 | apiEndpoint?: string;
|
31 | servicePath?: string;
|
32 | port?: string | number;
|
33 | sslCreds?: gax.grpc.ChannelCredentials;
|
34 | }
|
35 | export interface PageOptions {
|
36 | gaxOpts?: CallOptions;
|
37 | pageSize?: number;
|
38 | pageToken?: string;
|
39 | autoPaginate?: boolean;
|
40 | }
|
41 | export declare type GetSnapshotsCallback = RequestCallback<Snapshot, google.pubsub.v1.IListSnapshotsResponse>;
|
42 | export declare type GetSnapshotsResponse = PagedResponse<Snapshot, google.pubsub.v1.IListSnapshotsResponse>;
|
43 | export declare type GetSubscriptionsOptions = PageOptions & {
|
44 | topic?: string | Topic;
|
45 | };
|
46 | declare type GetAllSubscriptionsCallback = RequestCallback<Subscription, google.pubsub.v1.IListSubscriptionsResponse>;
|
47 | declare type GetAllSubscriptionsResponse = PagedResponse<Subscription, google.pubsub.v1.IListSubscriptionsResponse>;
|
48 | export declare type GetSubscriptionsCallback = GetAllSubscriptionsCallback | GetTopicSubscriptionsCallback;
|
49 | export declare type GetSubscriptionsResponse = GetAllSubscriptionsResponse | GetTopicSubscriptionsResponse;
|
50 | export declare type GetTopicsCallback = RequestCallback<Topic, google.pubsub.v1.IListTopicsResponse>;
|
51 | export declare type GetTopicsResponse = PagedResponse<Topic, google.pubsub.v1.IListTopicsResponse>;
|
52 | export declare type EmptyCallback = RequestCallback<google.protobuf.IEmpty>;
|
53 | export declare type EmptyResponse = [google.protobuf.IEmpty];
|
54 | export declare type ExistsCallback = RequestCallback<boolean>;
|
55 | export declare type ExistsResponse = [boolean];
|
56 | export declare type DetachedCallback = RequestCallback<boolean>;
|
57 | export declare type DetachedResponse = [boolean];
|
58 | export interface GetClientConfig {
|
59 | client: 'PublisherClient' | 'SubscriberClient';
|
60 | }
|
61 | export interface RequestConfig extends GetClientConfig {
|
62 | method: string;
|
63 | reqOpts?: object;
|
64 | gaxOpts?: CallOptions;
|
65 | }
|
66 | export interface ResourceCallback<Resource, Response> {
|
67 | (err: gax.grpc.ServiceError | null, resource?: Resource | null, response?: Response | null): void;
|
68 | }
|
69 | export declare type RequestCallback<T, R = void> = R extends void ? NormalCallback<T> : PagedCallback<T, R>;
|
70 | export interface NormalCallback<TResponse> {
|
71 | (err: gax.grpc.ServiceError | null, res?: TResponse | null): void;
|
72 | }
|
73 | export interface PagedCallback<Item, Response> {
|
74 | (err: gax.grpc.ServiceError | null, results?: Item[] | null, nextQuery?: {} | null, response?: Response | null): void;
|
75 | }
|
76 | export declare type PagedResponse<Item, Response> = [Item[]] | [Item[], {} | null, Response];
|
77 | export declare type ObjectStream<O> = {
|
78 | addListener(event: 'data', listener: (data: O) => void): ObjectStream<O>;
|
79 | emit(event: 'data', data: O): boolean;
|
80 | on(event: 'data', listener: (data: O) => void): ObjectStream<O>;
|
81 | once(event: 'data', listener: (data: O) => void): ObjectStream<O>;
|
82 | prependListener(event: 'data', listener: (data: O) => void): ObjectStream<O>;
|
83 | prependOnceListener(event: 'data', listener: (data: O) => void): ObjectStream<O>;
|
84 | } & Transform;
|
85 | interface GetClientCallback {
|
86 | (err: Error | null, gaxClient?: gax.ClientStub): void;
|
87 | }
|
88 | /**
|
89 | * @typedef {object} ClientConfig
|
90 | * @property {string} [projectId] The project ID from the Google Developer's
|
91 | * Console, e.g. 'grape-spaceship-123'. We will also check the environment
|
92 | * variable `GCLOUD_PROJECT` for your project ID. If your app is running in
|
93 | * an environment which supports {@link
|
94 | * https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application
|
95 | * Application Default Credentials}, your project ID will be detected
|
96 | * automatically.
|
97 | * @property {string} [keyFilename] Full path to the a .json, .pem, or .p12 key
|
98 | * downloaded from the Google Developers Console. If you provide a path to a
|
99 | * JSON file, the `projectId` option above is not necessary. NOTE: .pem and
|
100 | * .p12 require you to specify the `email` option as well.
|
101 | * @property {string} [apiEndpoint] The `apiEndpoint` from options will set the
|
102 | * host. If not set, the `PUBSUB_EMULATOR_HOST` environment variable from the
|
103 | * gcloud SDK is honored. We also check the `CLOUD_API_ENDPOINT_OVERRIDES_PUBSUB`
|
104 | * environment variable used by `gcloud alpha pubsub`. Otherwise the actual API
|
105 | * endpoint will be used. Note that if the URL doesn't end in '.googleapis.com',
|
106 | * we will assume that it's an emulator and disable strict SSL checks.
|
107 | * @property {string} [email] Account email address. Required when using a .pem
|
108 | * or .p12 keyFilename.
|
109 | * @property {object} [credentials] Credentials object.
|
110 | * @property {string} [credentials.client_email]
|
111 | * @property {string} [credentials.private_key]
|
112 | * @property {boolean} [autoRetry=true] Automatically retry requests if the
|
113 | * response is related to rate limits or certain intermittent server errors.
|
114 | * We will exponentially backoff subsequent requests by default.
|
115 | * @property {Constructor} [promise] Custom promise module to use instead of
|
116 | * native Promises.
|
117 | */
|
118 | /**
|
119 | * [Cloud Pub/Sub](https://developers.google.com/pubsub/overview) is a
|
120 | * reliable, many-to-many, asynchronous messaging service from Cloud
|
121 | * Platform.
|
122 | *
|
123 | * @class
|
124 | *
|
125 | * @see [Cloud Pub/Sub overview]{@link https://developers.google.com/pubsub/overview}
|
126 | *
|
127 | * @param {ClientConfig} [options] Configuration options.
|
128 | *
|
129 | * @example <caption>Import the client library</caption>
|
130 | * const {PubSub} = require('@google-cloud/pubsub');
|
131 | *
|
132 | * @example <caption>Create a client that uses <a href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application Default Credentials (ADC)</a>:</caption>
|
133 | * const pubsub = new PubSub();
|
134 | *
|
135 | * @example <caption>Create a client with <a href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit credentials</a>:</caption>
|
136 | * const pubsub = new PubSub({
|
137 | * projectId: 'your-project-id',
|
138 | * keyFilename: '/path/to/keyfile.json'
|
139 | * });
|
140 | *
|
141 | * @example <caption>include:samples/quickstart.js</caption>
|
142 | * region_tag:pubsub_quickstart_create_topic
|
143 | * Full quickstart example:
|
144 | */
|
145 | export declare class PubSub {
|
146 | options: ClientConfig;
|
147 | isEmulator: boolean;
|
148 | api: {
|
149 | [key: string]: gax.ClientStub;
|
150 | };
|
151 | auth: GoogleAuth;
|
152 | projectId: string;
|
153 | name?: string;
|
154 | Promise?: PromiseConstructor;
|
155 | getSubscriptionsStream: () => ObjectStream<Subscription>;
|
156 | getSnapshotsStream: () => ObjectStream<Snapshot>;
|
157 | getTopicsStream: () => ObjectStream<Topic>;
|
158 | isOpen: boolean;
|
159 | private schemaClient?;
|
160 | constructor(options?: ClientConfig);
|
161 | /**
|
162 | * Returns true if we have actually resolved the full project name.
|
163 | *
|
164 | * @returns {boolean} true if the name is resolved.
|
165 | */
|
166 | get isIdResolved(): boolean;
|
167 | close(): Promise<void>;
|
168 | close(callback: EmptyCallback): void;
|
169 | /**
|
170 | * Create a schema in the project.
|
171 | *
|
172 | * @see [Schemas: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/create}
|
173 | * @see {@link Schema#create}
|
174 | *
|
175 | * @throws {Error} If a schema ID or name is not provided.
|
176 | * @throws {Error} If an invalid SchemaType is provided.
|
177 | * @throws {Error} If an invalid schema definition is provided.
|
178 | *
|
179 | * @param {string} schemaId The name or ID of the subscription.
|
180 | * @param {SchemaType} type The type of the schema (Protobuf, Avro, etc).
|
181 | * @param {string} definition The text describing the schema in terms of the type.
|
182 | * @param {object} [options] Request configuration options, outlined
|
183 | * here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
|
184 | * @returns {Promise<Schema>}
|
185 | *
|
186 | * @example <caption>Create a schema.</caption>
|
187 | * const {PubSub} = require('@google-cloud/pubsub');
|
188 | * const pubsub = new PubSub();
|
189 | *
|
190 | * await pubsub.createSchema(
|
191 | * 'messageType',
|
192 | * SchemaTypes.Avro,
|
193 | * '{...avro definition...}'
|
194 | * );
|
195 | */
|
196 | createSchema(schemaId: string, type: SchemaType, definition: string, gaxOpts?: CallOptions): Promise<Schema>;
|
197 | createSubscription(topic: Topic | string, name: string, options?: CreateSubscriptionOptions): Promise<CreateSubscriptionResponse>;
|
198 | createSubscription(topic: Topic | string, name: string, callback: CreateSubscriptionCallback): void;
|
199 | createSubscription(topic: Topic | string, name: string, options: CreateSubscriptionOptions, callback: CreateSubscriptionCallback): void;
|
200 | createTopic(name: string | TopicMetadata, gaxOpts?: CallOptions): Promise<CreateTopicResponse>;
|
201 | createTopic(name: string | TopicMetadata, callback: CreateTopicCallback): void;
|
202 | createTopic(name: string | TopicMetadata, gaxOpts: CallOptions, callback: CreateTopicCallback): void;
|
203 | detachSubscription(name: string, gaxOpts?: CallOptions): Promise<DetachSubscriptionResponse>;
|
204 | detachSubscription(name: string, callback: DetachSubscriptionCallback): void;
|
205 | detachSubscription(name: string, gaxOpts: CallOptions, callback: DetachSubscriptionCallback): void;
|
206 | /**
|
207 | * Determine the appropriate endpoint to use for API requests, first trying
|
208 | * the `apiEndpoint` parameter. If that isn't set, we try the Pub/Sub emulator
|
209 | * environment variable (PUBSUB_EMULATOR_HOST). If that is also null, we try
|
210 | * the standard `gcloud alpha pubsub` environment variable
|
211 | * (CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB). Otherwise the default production
|
212 | * API is used.
|
213 | *
|
214 | * Note that if the URL doesn't end in '.googleapis.com', we will assume that
|
215 | * it's an emulator and disable strict SSL checks.
|
216 | *
|
217 | * @private
|
218 | */
|
219 | determineBaseUrl_(): void;
|
220 | /**
|
221 | * Get a list of schemas associated with your project.
|
222 | *
|
223 | * The returned AsyncIterable will resolve to {@link google.pubsub.v1.ISchema} objects.
|
224 | *
|
225 | * This method returns an async iterable. These objects can be adapted
|
226 | * to work in a Promise/then framework, as well as with callbacks, but
|
227 | * this discussion is considered out of scope for these docs.
|
228 | *
|
229 | * @see [Schemas: list API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/list}
|
230 | * @see [More about async iterators]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of}
|
231 | *
|
232 | * @param {google.pubsub.v1.SchemaView} [view] The type of schema objects
|
233 | * requested, which should be an enum value from {@link SchemaViews}. Defaults
|
234 | * to Full.
|
235 | * @param {object} [options] Request configuration options, outlined
|
236 | * here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
|
237 | * @returns {AsyncIterable<ISchema>}
|
238 | *
|
239 | * @example
|
240 | * for await (const s of pubsub.listSchemas()) {
|
241 | * const moreInfo = await s.get();
|
242 | * }
|
243 | */
|
244 | listSchemas(view?: SchemaView, options?: CallOptions): AsyncIterable<google.pubsub.v1.ISchema>;
|
245 | getSnapshots(options?: PageOptions): Promise<GetSnapshotsResponse>;
|
246 | getSnapshots(callback: GetSnapshotsCallback): void;
|
247 | getSnapshots(options: PageOptions, callback: GetSnapshotsCallback): void;
|
248 | getSubscriptions(options?: GetSubscriptionsOptions): Promise<GetSubscriptionsResponse>;
|
249 | getSubscriptions(callback: GetSubscriptionsCallback): void;
|
250 | getSubscriptions(options: GetSubscriptionsOptions, callback: GetSubscriptionsCallback): void;
|
251 | getTopics(options?: PageOptions): Promise<GetTopicsResponse>;
|
252 | getTopics(callback: GetTopicsCallback): void;
|
253 | getTopics(options: PageOptions, callback: GetTopicsCallback): void;
|
254 | /**
|
255 | * Retrieve a client configuration, suitable for passing into a GAPIC
|
256 | * 'v1' class constructor. This will fill out projectId, emulator URLs,
|
257 | * and so forth.
|
258 | *
|
259 | * @returns {Promise<ClientConfig>} the filled client configuration.
|
260 | */
|
261 | getClientConfig(): Promise<ClientConfig>;
|
262 | /**
|
263 | * Gets a schema client, creating one if needed.
|
264 | * @private
|
265 | */
|
266 | getSchemaClient_(): Promise<SchemaServiceClient>;
|
267 | /**
|
268 | * Callback function to PubSub.getClient_().
|
269 | * @private
|
270 | * @callback GetClientCallback
|
271 | * @param err - Error, if any.
|
272 | * @param gaxClient - The gax client specified in RequestConfig.client.
|
273 | * Typed any since it's importing Javascript source.
|
274 | */
|
275 | /**
|
276 | * Get the PubSub client object.
|
277 | *
|
278 | * @private
|
279 | *
|
280 | * @param {object} config Configuration object.
|
281 | * @param {object} config.gaxOpts GAX options.
|
282 | * @param {function} config.method The gax method to call.
|
283 | * @param {object} config.reqOpts Request options.
|
284 | * @param {function} [callback] The callback function.
|
285 | */
|
286 | getClient_(config: GetClientConfig, callback: GetClientCallback): void;
|
287 | /**
|
288 | * Get the PubSub client object.
|
289 | *
|
290 | * @private
|
291 | *
|
292 | * @param {object} config Configuration object.
|
293 | * @param {object} config.gaxOpts GAX options.
|
294 | * @param {function} config.method The gax method to call.
|
295 | * @param {object} config.reqOpts Request options.
|
296 | * @returns {Promise}
|
297 | */
|
298 | getClientAsync_(config: GetClientConfig): Promise<gax.ClientStub>;
|
299 | /**
|
300 | * Close all open client objects.
|
301 | *
|
302 | * @private
|
303 | *
|
304 | * @returns {Promise}
|
305 | */
|
306 | closeAllClients_(): Promise<void>;
|
307 | /**
|
308 | * Funnel all API requests through this method, to be sure we have a project
|
309 | * ID.
|
310 | *
|
311 | * @private
|
312 | *
|
313 | * @param {object} config Configuration object.
|
314 | * @param {object} config.gaxOpts GAX options.
|
315 | * @param {function} config.method The gax method to call.
|
316 | * @param {object} config.reqOpts Request options.
|
317 | * @param {function} [callback] The callback function.
|
318 | */
|
319 | request<T, R = void>(config: RequestConfig, callback: RequestCallback<T, R>): void;
|
320 | /**
|
321 | * Create a Schema object, representing a schema within the project.
|
322 | * See {@link PubSub#createSchema} or {@link Schema#create} to create a schema.
|
323 | *
|
324 | * @throws {Error} If a name is not provided.
|
325 | *
|
326 | * @param {string} name The ID or name of the schema.
|
327 | * @returns {Schema} A {@link Schema} instance.
|
328 | *
|
329 | * @example
|
330 | * const {PubSub} = require('@google-cloud/pubsub');
|
331 | * const pubsub = new PubSub();
|
332 | *
|
333 | * const schema = pubsub.schema('my-schema');
|
334 | */
|
335 | schema(idOrName: string): Schema;
|
336 | /**
|
337 | * Create a Snapshot object. See {@link Subscription#createSnapshot} to
|
338 | * create a snapshot.
|
339 | *
|
340 | * @throws {Error} If a name is not provided.
|
341 | *
|
342 | * @param {string} name The name of the snapshot.
|
343 | * @returns {Snapshot} A {@link Snapshot} instance.
|
344 | *
|
345 | * @example
|
346 | * const {PubSub} = require('@google-cloud/pubsub');
|
347 | * const pubsub = new PubSub();
|
348 | *
|
349 | * const snapshot = pubsub.snapshot('my-snapshot');
|
350 | */
|
351 | snapshot(name: string): Snapshot;
|
352 | /**
|
353 | * Create a Subscription object. This command by itself will not run any API
|
354 | * requests. You will receive a {@link Subscription} object,
|
355 | * which will allow you to interact with a subscription.
|
356 | *
|
357 | * @throws {Error} If subscription name is omitted.
|
358 | *
|
359 | * @param {string} name Name of the subscription.
|
360 | * @param {SubscriberOptions} [options] Configuration object.
|
361 | * @returns {Subscription} A {@link Subscription} instance.
|
362 | *
|
363 | * @example
|
364 | * const {PubSub} = require('@google-cloud/pubsub');
|
365 | * const pubsub = new PubSub();
|
366 | *
|
367 | * const subscription = pubsub.subscription('my-subscription');
|
368 | *
|
369 | * // Register a listener for `message` events.
|
370 | * subscription.on('message', function(message) {
|
371 | * // Called every time a message is received.
|
372 | * // message.id = ID of the message.
|
373 | * // message.ackId = ID used to acknowledge the message receival.
|
374 | * // message.data = Contents of the message.
|
375 | * // message.attributes = Attributes of the message.
|
376 | * // message.publishTime = Date when Pub/Sub received the message.
|
377 | * });
|
378 | */
|
379 | subscription(name: string, options?: SubscriptionOptions): Subscription;
|
380 | /**
|
381 | * Create a Topic object. See {@link PubSub#createTopic} to create a topic.
|
382 | *
|
383 | * @throws {Error} If a name is not provided.
|
384 | *
|
385 | * @param {string} name The name of the topic.
|
386 | * @param {PublishOptions} [options] Publisher configuration object.
|
387 | * @returns {Topic} A {@link Topic} instance.
|
388 | *
|
389 | * @example
|
390 | * const {PubSub} = require('@google-cloud/pubsub');
|
391 | * const pubsub = new PubSub();
|
392 | *
|
393 | * const topic = pubsub.topic('my-topic');
|
394 | */
|
395 | topic(name: string, options?: PublishOptions): Topic;
|
396 | /**
|
397 | * Validate a schema definition.
|
398 | *
|
399 | * @see [Schemas: validateSchema API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/validate}
|
400 | *
|
401 | * @throws {Error} if the validation fails.
|
402 | *
|
403 | * @param {ISchema} schema The schema definition you wish to validate.
|
404 | * @param {object} [options] Request configuration options, outlined
|
405 | * here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
|
406 | * @returns {Promise<void>}
|
407 | */
|
408 | validateSchema(schema: ISchema, gaxOpts?: CallOptions): Promise<void>;
|
409 | /*!
|
410 | * Format the name of a project. A project's full name is in the
|
411 | * format of projects/{projectId}.
|
412 | *
|
413 | * The GAPIC client should do this for us, but since we maintain
|
414 | * names rather than IDs, this is simpler.
|
415 | *
|
416 | * @private
|
417 | */
|
418 | static formatName_(name: string): string;
|
419 | }
|
420 | export {};
|