Package @google-cloud/pubsub (4.0.0)



Thrown when an error is detected in an ack/nack/modack call, when exactly-once delivery is enabled on the subscription. This will only be thrown for actual errors that can't be retried.


Represents a debug message the user might want to print out for logging while debugging or whatnot. These will always come by way of the 'error' channel on streams or other event emitters. It's completely fine to ignore them, as some will just be verbose logging info, but they may help figure out what's going wrong. Support may also ask you to catch these channels, which you can do like so:

subscription.on('debug', msg => console.log(msg.message));

These values are _not_ guaranteed to remain stable, even within a major version, so don't depend on them for your program logic. Debug outputs may be added or removed at any time, without warning.


Duration class with an interface similar to the tc39 Temporal proposal. Since it's not fully finalized, and polyfills have inconsistent compatibility, for now this shim class will be used to set durations in Pub/Sub.

This class will remain here for at least the next major version, eventually to be replaced by the tc39 Temporal built-in.


[IAM (Identity and Access Management)]( allows you to set permissions on individual resources and offers a wider range of roles: editor, owner, publisher, subscriber, and viewer. This gives you greater flexibility and allows you to set more fine-grained access control.

For example: * Grant access on a per-topic or per-subscription basis, rather than for the whole Cloud project. * Grant access with limited capabilities, such as to only publish messages to a topic, or to only to consume messages from a subscription, but not to delete the topic or subscription.

*The IAM access control features described in this document are Beta, including the API methods to get and set IAM policies, and to test IAM permissions. Cloud Pub/Sub's use of IAM features is not covered by any SLA or deprecation policy, and may be subject to backward-incompatible changes.*


Message objects provide a simple interface for users to get message data and acknowledge the message.

Represents a ClientLibrarySettings.

Represents a CommonLanguageSettings.

Represents a CppSettings.

Represents a CustomHttpPattern.

Represents a DotnetSettings.

Represents a GoSettings.

Represents a Http.

Represents a HttpRule.

Represents a JavaSettings.

Represents a MethodSettings.

Represents a LongRunning.

Represents a NodeSettings.

Represents a PhpSettings.

Represents a Publishing.

Represents a PythonSettings.

Represents a ResourceDescriptor.

Represents a ResourceReference.

Represents a RubySettings.

Represents a DescriptorProto.

Represents an ExtensionRange.

Represents a ReservedRange.

Represents a Duration.

Represents an Empty.

Represents an EnumDescriptorProto.

Represents an EnumReservedRange.

Represents an EnumOptions.

Represents an EnumValueDescriptorProto.

Represents an EnumValueOptions.

Represents an ExtensionRangeOptions.

Represents a FieldDescriptorProto.

Represents a FieldMask.

Represents a FieldOptions.

Represents a FileDescriptorProto.

Represents a FileDescriptorSet.

Represents a FileOptions.

Represents a GeneratedCodeInfo.

Represents an Annotation.

Represents a MessageOptions.

Represents a MethodDescriptorProto.

Represents a MethodOptions.

Represents an OneofDescriptorProto.

Represents an OneofOptions.

Represents a ServiceDescriptorProto.

Represents a ServiceOptions.

Represents a SourceCodeInfo.

Represents a Location.

Represents a Timestamp.

Represents an UninterpretedOption.

Represents a NamePart.

Represents an AcknowledgeRequest.

Represents a BigQueryConfig.

Represents a CloudStorageConfig.

Represents an AvroConfig.

Represents a TextConfig.

Represents a CommitSchemaRequest.

Represents a CreateSchemaRequest.

Represents a CreateSnapshotRequest.

Represents a DeadLetterPolicy.

Represents a DeleteSchemaRequest.

Represents a DeleteSchemaRevisionRequest.

Represents a DeleteSnapshotRequest.

Represents a DeleteSubscriptionRequest.

Represents a DeleteTopicRequest.

Represents a DetachSubscriptionRequest.

Represents a DetachSubscriptionResponse.

Represents an ExpirationPolicy.

Represents a GetSchemaRequest.

Represents a GetSnapshotRequest.

Represents a GetSubscriptionRequest.

Represents a GetTopicRequest.

Represents a ListSchemaRevisionsRequest.

Represents a ListSchemaRevisionsResponse.

Represents a ListSchemasRequest.

Represents a ListSchemasResponse.

Represents a ListSnapshotsRequest.

Represents a ListSnapshotsResponse.

Represents a ListSubscriptionsRequest.

Represents a ListSubscriptionsResponse.

Represents a ListTopicSnapshotsRequest.

Represents a ListTopicSnapshotsResponse.

Represents a ListTopicsRequest.

Represents a ListTopicsResponse.

Represents a ListTopicSubscriptionsRequest.

Represents a ListTopicSubscriptionsResponse.

Represents a MessageStoragePolicy.

Represents a ModifyAckDeadlineRequest.

Represents a ModifyPushConfigRequest.

Represents a Publisher

Represents a PublishRequest.

Represents a PublishResponse.

Represents a PubsubMessage.

Represents a PullRequest.

Represents a PullResponse.

Represents a PushConfig.

Represents a NoWrapper.

Represents an OidcToken.

Represents a PubsubWrapper.

Represents a ReceivedMessage.

Represents a RetryPolicy.

Represents a RollbackSchemaRequest.

Represents a Schema.

Represents a SchemaService

Represents a SchemaSettings.

Represents a SeekRequest.

Represents a SeekResponse.

Represents a Snapshot.

Represents a StreamingPullRequest.

Represents a StreamingPullResponse.

Represents an AcknowledgeConfirmation.

Represents a ModifyAckDeadlineConfirmation.

Represents a SubscriptionProperties.

Represents a Subscriber

Represents a Subscription.

Represents a Topic.

Represents an UpdateSnapshotRequest.

Represents an UpdateSubscriptionRequest.

Represents an UpdateTopicRequest.

Represents a ValidateMessageRequest.

Represents a ValidateMessageResponse.

Represents a ValidateSchemaRequest.

Represents a ValidateSchemaResponse.


Exception to be thrown during failed ordered publish.



[Cloud Pub/Sub]( is a reliable, many-to-many, asynchronous messaging service from Cloud Platform.


A Schema object allows you to interact with a Cloud Pub/Sub schema.

This should only be instantiated by the PubSub class. To obtain an instance for end user usage, call pubsub.schema().


A Snapshot object will give you access to your Cloud Pub/Sub snapshot.

Snapshots are sometimes retrieved when using various methods:

Snapshots may be created with:

  • You can use snapshots to seek a subscription to a specific point in time.



A Subscription object will give you access to your Cloud Pub/Sub subscription.

Subscriptions are sometimes retrieved when using various methods:

Subscription objects may be created directly with:

All Subscription objects are instances of an [EventEmitter]( The subscription will pull for messages automatically as long as there is at least one listener assigned for the message event. Available events:

Upon receipt of a message: on(event: 'message', listener: (message: Message) => void): this;

Upon receipt of an error: on(event: 'error', listener: (error: Error) => void): this;

Upon receipt of a (non-fatal) debug warning: on(event: 'debug', listener: (msg: DebugMessage) => void): this;

Upon the closing of the subscriber: on(event: 'close', listener: Function): this;

By default Subscription objects allow you to process 100 messages at the same time. You can fine tune this value by adjusting the options.flowControl.maxMessages option.

If your subscription is seeing more re-deliveries than preferable, you might try increasing your options.ackDeadline value or decreasing the options.streamingOptions.maxStreams value.

Subscription objects handle ack management, by automatically extending the ack deadline while the message is being processed, to then issue the ack or nack of such message when the processing is done. **Note:** message redelivery is still possible.

By default each PubSub instance can handle 100 open streams, with default options this translates to less than 20 Subscriptions per PubSub instance. If you wish to create more Subscriptions than that, you can either create multiple PubSub instances or lower the options.streamingOptions.maxStreams value on each Subscription object.


A Topic object allows you to interact with a Cloud Pub/Sub topic.


The service that an application uses to manipulate topics, and to send messages to a topic. v1


Service for doing schema-related operations. v1


The service that an application uses to manipulate subscriptions and to consume messages from a subscription via the Pull method or by establishing a bi-directional stream using the StreamingPull method. v1





Simplified interface analogous to the tc39 Temporal.Duration parameter to from(). This doesn't support the full gamut (years, days).


FlowControlOptions {number} [maxOutstandingMessages] The maximum number of messages to buffer before publisher flow control kicks in. {number} [maxOutstandingBytes] The maximum number of bytes to buffer before publisher flow control kicks in.


Shows which IAM permissions is allowed. The key to this object are the IAM permissions (string) and the values are booleans, true if permissions are granted to the corresponding key.


Properties of a ClientLibrarySettings.

Properties of a CommonLanguageSettings.

Properties of a CppSettings.

Properties of a CustomHttpPattern.

Properties of a DotnetSettings.

Properties of a GoSettings.

Properties of a Http.

Properties of a HttpRule.

Properties of a JavaSettings.

Properties of a MethodSettings.

Properties of a NodeSettings.

Properties of a PhpSettings.

Properties of a Publishing.

Properties of a PythonSettings.

Properties of a ResourceDescriptor.

Properties of a ResourceReference.

Properties of a RubySettings.

Properties of a LongRunning.

Properties of an ExtensionRange.

Properties of a ReservedRange.

Properties of an EnumReservedRange.

Properties of an Annotation.

Properties of a DescriptorProto.

Properties of a Duration.

Properties of an Empty.

Properties of an EnumDescriptorProto.

Properties of an EnumOptions.

Properties of an EnumValueDescriptorProto.

Properties of an EnumValueOptions.

Properties of an ExtensionRangeOptions.

Properties of a FieldDescriptorProto.

Properties of a FieldMask.

Properties of a FieldOptions.

Properties of a FileDescriptorProto.

Properties of a FileDescriptorSet.

Properties of a FileOptions.

Properties of a GeneratedCodeInfo.

Properties of a MessageOptions.

Properties of a MethodDescriptorProto.

Properties of a MethodOptions.

Properties of an OneofDescriptorProto.

Properties of an OneofOptions.

Properties of a ServiceDescriptorProto.

Properties of a ServiceOptions.

Properties of a SourceCodeInfo.

Properties of a Timestamp.

Properties of an UninterpretedOption.

Properties of a Location.

Properties of a NamePart.

Properties of an AvroConfig.

Properties of a TextConfig.

Properties of an AcknowledgeRequest.

Properties of a BigQueryConfig.

Properties of a CloudStorageConfig.

Properties of a CommitSchemaRequest.

Properties of a CreateSchemaRequest.

Properties of a CreateSnapshotRequest.

Properties of a DeadLetterPolicy.

Properties of a DeleteSchemaRequest.

Properties of a DeleteSchemaRevisionRequest.

Properties of a DeleteSnapshotRequest.

Properties of a DeleteSubscriptionRequest.

Properties of a DeleteTopicRequest.

Properties of a DetachSubscriptionRequest.

Properties of a DetachSubscriptionResponse.

Properties of an ExpirationPolicy.

Properties of a GetSchemaRequest.

Properties of a GetSnapshotRequest.

Properties of a GetSubscriptionRequest.

Properties of a GetTopicRequest.

Properties of a ListSchemaRevisionsRequest.

Properties of a ListSchemaRevisionsResponse.

Properties of a ListSchemasRequest.

Properties of a ListSchemasResponse.

Properties of a ListSnapshotsRequest.

Properties of a ListSnapshotsResponse.

Properties of a ListSubscriptionsRequest.

Properties of a ListSubscriptionsResponse.

Properties of a ListTopicSnapshotsRequest.

Properties of a ListTopicSnapshotsResponse.

Properties of a ListTopicsRequest.

Properties of a ListTopicsResponse.

Properties of a ListTopicSubscriptionsRequest.

Properties of a ListTopicSubscriptionsResponse.

Properties of a MessageStoragePolicy.

Properties of a ModifyAckDeadlineRequest.

Properties of a ModifyPushConfigRequest.

Properties of a PublishRequest.

Properties of a PublishResponse.

Properties of a PubsubMessage.

Properties of a PullRequest.

Properties of a PullResponse.

Properties of a PushConfig.

Properties of a ReceivedMessage.

Properties of a RetryPolicy.

Properties of a RollbackSchemaRequest.

Properties of a Schema.

Properties of a SchemaSettings.

Properties of a SeekRequest.

Properties of a SeekResponse.

Properties of a Snapshot.

Properties of a StreamingPullRequest.

Properties of a StreamingPullResponse.

Properties of a Subscription.

Properties of a Topic.

Properties of an UpdateSnapshotRequest.

Properties of an UpdateSubscriptionRequest.

Properties of an UpdateTopicRequest.

Properties of a ValidateMessageRequest.

Properties of a ValidateMessageResponse.

Properties of a ValidateSchemaRequest.

Properties of a ValidateSchemaResponse.

Properties of a NoWrapper.

Properties of an OidcToken.

Properties of a PubsubWrapper.

Properties of an AcknowledgeConfirmation.

Properties of a ModifyAckDeadlineConfirmation.

Properties of a SubscriptionProperties.



Schema metadata that might be gathered from a Pub/Sub message. This is created for you from .


{object} SubscriberOptions {number} [ackDeadline=10] Acknowledge deadline in seconds. If left unset, the initial value will be 10 seconds, but it will evolve into the 99th percentile time it takes to acknowledge a message, subject to the limitations of minAckDeadline and maxAckDeadline. If ackDeadline is set by the user, then the min/max values will be set to match it. New code should prefer setting minAckDeadline and maxAckDeadline directly. {Duration} [minAckDeadline] The minimum time that ackDeadline should ever have, while it's under library control. {Duration} [maxAckDeadline] The maximum time that ackDeadline should ever have, while it's under library control. {BatchOptions} [batching] Request batching options. {FlowControlOptions} [flowControl] Flow control options. {boolean} [useLegacyFlowControl] Disables enforcing flow control settings at the Cloud PubSub server and uses the less accurate method of only enforcing flow control at the client side. {MessageStreamOptions} [streamingOptions] Streaming options.



ClientLibraryDestination enum.

ClientLibraryOrganization enum.

FieldBehavior enum.

LaunchStage enum.

History enum.

Style enum.

Label enum.

Type enum.

CType enum.

JSType enum.

OptionRetention enum.

OptionTargetType enum.

OptimizeMode enum.

Semantic enum.

IdempotencyLevel enum.

State enum.

State enum.

Encoding enum.

Type enum.

SchemaView enum.

State enum.



AckResponses: {
    PermissionDenied: "PERMISSION_DENIED";
    FailedPrecondition: "FAILED_PRECONDITION";
    Success: "SUCCESS";
    Invalid: "INVALID";
    Other: "OTHER";


Encodings: {
    Json: "JSON";
    Binary: "BINARY";


SchemaTypes: {
    ProtocolBuffer: "PROTOCOL_BUFFER";
    Avro: "AVRO";


SchemaViews: {
    Basic: "BASIC";
    Full: "FULL";

Type Aliases


export type AckResponse = ValueOf


export type Attributes = Record

Strings are the only allowed values for keys and values in message attributes.


export type CreateSchemaResponse = google.pubsub.v1.Schema;


export type CreateSnapshotCallback = ResourceCallback


export type CreateSnapshotResponse = [Snapshot, google.pubsub.v1.ISnapshot];


export type CreateSubscriptionCallback = SubscriptionCallback;


export type CreateSubscriptionOptions = SubscriptionMetadata & {
    gaxOpts?: CallOptions;
    flowControl?: FlowControlOptions;


export type CreateSubscriptionResponse = SubscriptionResponse;


export type CreateTopicCallback = TopicCallback;


export type CreateTopicResponse = TopicResponse;


export type EmptyCallback = RequestCallback


export type EmptyResponse = [google.protobuf.IEmpty];


export type ExistsCallback = RequestCallback


export type ExistsResponse = [boolean];


export type GetPolicyCallback = RequestCallback


export type GetPolicyResponse = [Policy];


export type GetSnapshotsCallback = RequestCallback


export type GetSnapshotsResponse = PagedResponse


export type GetSubscriptionCallback = SubscriptionCallback;


export type GetSubscriptionMetadataCallback = MetadataCallback;


export type GetSubscriptionMetadataResponse = MetadataResponse;


export type GetSubscriptionOptions = CallOptions & {
    autoCreate?: boolean;


export type GetSubscriptionResponse = SubscriptionResponse;


export type GetSubscriptionsCallback = GetAllSubscriptionsCallback | GetTopicSubscriptionsCallback;


export type GetSubscriptionsResponse = GetAllSubscriptionsResponse | GetTopicSubscriptionsResponse;


export type GetTopicCallback = TopicCallback;


export type GetTopicMetadataCallback = MetadataCallback;


export type GetTopicMetadataResponse = MetadataResponse;


export type GetTopicOptions = CallOptions & {
    autoCreate?: boolean;


export type GetTopicResponse = TopicResponse;


export type GetTopicsCallback = RequestCallback


export type GetTopicsResponse = PagedResponse


export type GetTopicSubscriptionsCallback = RequestCallback


export type GetTopicSubscriptionsResponse = PagedResponse


export type ICreateSchemaRequest = google.pubsub.v1.ICreateSchemaRequest;


export type ISchema = google.pubsub.v1.ISchema;


export type Policy = {
    etag?: string | Buffer;
} & Omit

type CreateTopicCallback = (error: (Error|null), response?: google.pubsub.v1.Topic) => void;

Callback as used by .

type DeleteTopicCallback = (error: (Error|null), response?: google.protobuf.Empty) => void;

Callback as used by .

type DetachSubscriptionCallback = (error: (Error|null), response?: google.pubsub.v1.DetachSubscriptionResponse) => void;

Callback as used by .

type GetTopicCallback = (error: (Error|null), response?: google.pubsub.v1.Topic) => void;

Callback as used by .

type ListTopicsCallback = (error: (Error|null), response?: google.pubsub.v1.ListTopicsResponse) => void;

Callback as used by .

type ListTopicSnapshotsCallback = (error: (Error|null), response?: google.pubsub.v1.ListTopicSnapshotsResponse) => void;

Callback as used by .

type ListTopicSubscriptionsCallback = (error: (Error|null), response?: google.pubsub.v1.ListTopicSubscriptionsResponse) => void;

Callback as used by .

type PublishCallback = (error: (Error|null), response?: google.pubsub.v1.PublishResponse) => void;

Callback as used by .

type UpdateTopicCallback = (error: (Error|null), response?: google.pubsub.v1.Topic) => void;

Callback as used by .

type CommitSchemaCallback = (error: (Error|null), response?: google.pubsub.v1.Schema) => void;

Callback as used by .

type CreateSchemaCallback = (error: (Error|null), response?: google.pubsub.v1.Schema) => void;

Callback as used by .

type DeleteSchemaCallback = (error: (Error|null), response?: google.protobuf.Empty) => void;

Callback as used by .

type DeleteSchemaRevisionCallback = (error: (Error|null), response?: google.pubsub.v1.Schema) => void;

Callback as used by .

type GetSchemaCallback = (error: (Error|null), response?: google.pubsub.v1.Schema) => void;

Callback as used by .

type ListSchemaRevisionsCallback = (error: (Error|null), response?: google.pubsub.v1.ListSchemaRevisionsResponse) => void;

Callback as used by .

type ListSchemasCallback = (error: (Error|null), response?: google.pubsub.v1.ListSchemasResponse) => void;

Callback as used by .

type RollbackSchemaCallback = (error: (Error|null), response?: google.pubsub.v1.Schema) => void;

Callback as used by .

type ValidateMessageCallback = (error: (Error|null), response?: google.pubsub.v1.ValidateMessageResponse) => void;

Callback as used by .

type ValidateSchemaCallback = (error: (Error|null), response?: google.pubsub.v1.ValidateSchemaResponse) => void;

Callback as used by .

type AcknowledgeCallback = (error: (Error|null), response?: google.protobuf.Empty) => void;

Callback as used by .

type CreateSnapshotCallback = (error: (Error|null), response?: google.pubsub.v1.Snapshot) => void;

Callback as used by .

type CreateSubscriptionCallback = (error: (Error|null), response?: google.pubsub.v1.Subscription) => void;

Callback as used by .

type DeleteSnapshotCallback = (error: (Error|null), response?: google.protobuf.Empty) => void;

Callback as used by .

type DeleteSubscriptionCallback = (error: (Error|null), response?: google.protobuf.Empty) => void;

Callback as used by .

type GetSnapshotCallback = (error: (Error|null), response?: google.pubsub.v1.Snapshot) => void;

Callback as used by .

type GetSubscriptionCallback = (error: (Error|null), response?: google.pubsub.v1.Subscription) => void;

Callback as used by .

type ListSnapshotsCallback = (error: (Error|null), response?: google.pubsub.v1.ListSnapshotsResponse) => void;

Callback as used by .

type ListSubscriptionsCallback = (error: (Error|null), response?: google.pubsub.v1.ListSubscriptionsResponse) => void;

Callback as used by .

type ModifyAckDeadlineCallback = (error: (Error|null), response?: google.protobuf.Empty) => void;

Callback as used by .

type ModifyPushConfigCallback = (error: (Error|null), response?: google.protobuf.Empty) => void;

Callback as used by .

type PullCallback = (error: (Error|null), response?: google.pubsub.v1.PullResponse) => void;

Callback as used by .

type SeekCallback = (error: (Error|null), response?: google.pubsub.v1.SeekResponse) => void;

Callback as used by .

type StreamingPullCallback = (error: (Error|null), response?: google.pubsub.v1.StreamingPullResponse) => void;

Callback as used by .

type UpdateSnapshotCallback = (error: (Error|null), response?: google.pubsub.v1.Snapshot) => void;

Callback as used by .

type UpdateSubscriptionCallback = (error: (Error|null), response?: google.pubsub.v1.Subscription) => void;

Callback as used by .


export type PublishCallback = RequestCallback


export type PushConfig = google.pubsub.v1.IPushConfig;


export type SchemaEncoding = keyof typeof google.pubsub.v1.Encoding;


export type SchemaType = keyof typeof google.pubsub.v1.Schema.Type;


export type SchemaView = keyof typeof google.pubsub.v1.SchemaView;


export type SeekCallback = RequestCallback


export type SeekResponse = [google.pubsub.v1.ISeekResponse];


export type SetPolicyCallback = RequestCallback


export type SetPolicyResponse = [Policy];


export type SetSubscriptionMetadataCallback = MetadataCallback;


export type SetSubscriptionMetadataResponse = MetadataResponse;


export type SetTopicMetadataCallback = MetadataCallback;


export type SetTopicMetadataResponse = MetadataResponse;


export type SubscriptionCloseCallback = (err?: Error) => void;


export type SubscriptionMetadata = {
    messageRetentionDuration?: google.protobuf.IDuration | number;
    pushEndpoint?: string;
    oidcToken?: OidcToken;
} & Omit


export type SubscriptionOptions = SubscriberOptions & {
    topic?: Topic;


export type TestIamPermissionsCallback = ResourceCallback


export type TestIamPermissionsResponse = [


export type TopicMetadata = google.pubsub.v1.ITopic;


export type TotalOfUnit = 'hour' | 'minute' | 'second' | 'millisecond';

Simplified list of values to pass to Duration.totalOf(). This list is taken from the tc39 Temporal.Duration proposal, but larger and smaller units have been left off.