@google-cloud/pubsub 3.2.1 → 3.4.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@
 
 [1]: https://www.npmjs.com/package/@google-cloud/pubsub?activeTab=versions
 
+## [3.4.0](https://github.com/googleapis/nodejs-pubsub/compare/v3.3.0...v3.4.0) (2023-03-06)
+
+
+### Features
+
+* Add google.api.method.signature to update methods ([1e28405](https://github.com/googleapis/nodejs-pubsub/commit/1e2840529a8451c94d5d845062da84729b7843db))
+* Add temporary_failed_ack_ids to ModifyAckDeadlineConfirmation ([1e28405](https://github.com/googleapis/nodejs-pubsub/commit/1e2840529a8451c94d5d845062da84729b7843db))
+* Make INTERNAL a retryable error for Pull ([#1681](https://github.com/googleapis/nodejs-pubsub/issues/1681)) ([1e28405](https://github.com/googleapis/nodejs-pubsub/commit/1e2840529a8451c94d5d845062da84729b7843db))
+
+
+### Bug Fixes
+
+* Don't do multiple drains per publish() in message queues unless requested ([#1691](https://github.com/googleapis/nodejs-pubsub/issues/1691)) ([d9b3a63](https://github.com/googleapis/nodejs-pubsub/commit/d9b3a63ddbfec0581a0e05fdbfcf9e9326b3dcf9))
+
+## [3.3.0](https://github.com/googleapis/nodejs-pubsub/compare/v3.2.1...v3.3.0) (2023-01-23)
+
+
+### Features
+
+* Add schema evolution methods and fields ([#1672](https://github.com/googleapis/nodejs-pubsub/issues/1672)) ([7a5bc29](https://github.com/googleapis/nodejs-pubsub/commit/7a5bc29e8a39e5c1991a5eae4200a5045f21997d))
+
+
+### Bug Fixes
+
+* Remove redundant .then() ([#1671](https://github.com/googleapis/nodejs-pubsub/issues/1671)) ([108edc3](https://github.com/googleapis/nodejs-pubsub/commit/108edc3cd2d3d512e2a9777a68541dae1f6aba23))
+
 ## [3.2.1](https://github.com/googleapis/nodejs-pubsub/compare/v3.2.0...v3.2.1) (2022-11-04)
 
 

package/README.md

@@ -13,7 +13,7 @@
 [Cloud Pub/Sub](https://cloud.google.com/pubsub/docs) is a fully-managed real-time messaging service that allows
 you to send and receive messages between independent applications.
 
-This document contains links to an [API reference](https://googleapis.dev/nodejs/pubsub/latest/index.html#reference), samples,
+This document contains links to an [API reference](https://cloud.google.com/nodejs/docs/reference/pubsub/latest/overview), samples,
 and other resources useful to developing Node.js applications.
 For additional help developing Pub/Sub applications, in Node.js and other languages, see our
 [Pub/Sub quickstart](https://cloud.google.com/pubsub/docs/quickstart-client-libraries),
@@ -96,7 +96,7 @@ async function quickstart(
   });
 
   // Send a message to the topic
-  topic.publish(Buffer.from('Test message!'));
+  topic.publishMessage({data: Buffer.from('Test message!')});
 }
 
 ```
@@ -174,6 +174,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-pubsub/tree
 | Test Subscription Permissions | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/testSubscriptionPermissions.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/testSubscriptionPermissions.js,samples/README.md) |
 | Test Topic Permissions | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/testTopicPermissions.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/testTopicPermissions.js,samples/README.md) |
 | Update Dead Letter Policy | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/updateDeadLetterPolicy.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/updateDeadLetterPolicy.js,samples/README.md) |
+| Validate a schema definition | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/validateSchema.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/validateSchema.js,samples/README.md) |
 
 
 

package/build/protos/google/pubsub/v1/pubsub.proto

@@ -60,6 +60,7 @@ service Publisher {
       patch: "/v1/{topic.name=projects/*/topics/*}"
       body: "*"
     };
+    option (google.api.method_signature) = "topic,update_mask";
   }
 
   // Adds one or more messages to the topic. Returns `NOT_FOUND` if the topic
@@ -157,6 +158,16 @@ message SchemaSettings {
 
   // The encoding of messages validated against `schema`.
   Encoding encoding = 2;
+
+  // The minimum (inclusive) revision allowed for validating messages. If empty
+  // or not present, allow any revision to be validated against last_revision or
+  // any revision created before.
+  string first_revision_id = 3;
+
+  // The maximum (inclusive) revision allowed for validating messages. If empty
+  // or not present, allow any revision to be validated against first_revision
+  // or any revision created after.
+  string last_revision_id = 4;
 }
 
 // A topic resource.
@@ -204,7 +215,7 @@ message Topic {
   // timestamp](https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)
   // that is up to `message_retention_duration` in the past. If this field is
   // not set, message retention is controlled by settings on individual
-  // subscriptions. Cannot be more than 7 days or less than 10 minutes.
+  // subscriptions. Cannot be more than 31 days or less than 10 minutes.
   google.protobuf.Duration message_retention_duration = 8;
 }
 
@@ -243,6 +254,8 @@ message PubsubMessage {
   // delivered to subscribers in the order in which they are received by the
   // Pub/Sub system. All `PubsubMessage`s published in a given `PublishRequest`
   // must specify the same `ordering_key` value.
+  // For more information, see [ordering
+  // messages](https://cloud.google.com/pubsub/docs/ordering).
   string ordering_key = 5;
 }
 
@@ -451,6 +464,7 @@ service Subscriber {
       patch: "/v1/{subscription.name=projects/*/subscriptions/*}"
       body: "*"
     };
+    option (google.api.method_signature) = "subscription,update_mask";
   }
 
   // Lists matching subscriptions.
@@ -505,9 +519,7 @@ service Subscriber {
     option (google.api.method_signature) = "subscription,ack_ids";
   }
 
-  // Pulls messages from the server. The server may return `UNAVAILABLE` if
-  // there are too many concurrent pull requests pending for the given
-  // subscription.
+  // Pulls messages from the server.
   rpc Pull(PullRequest) returns (PullResponse) {
     option (google.api.http) = {
       post: "/v1/{subscription=projects/*/subscriptions/*}:pull"
@@ -544,10 +556,10 @@ service Subscriber {
   }
 
   // Gets the configuration details of a snapshot. Snapshots are used in
-  // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a>
-  // operations, which allow you to manage message acknowledgments in bulk. That
-  // is, you can set the acknowledgment state of messages in an existing
-  // subscription to the state captured by a snapshot.
+  // [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
+  // which allow you to manage message acknowledgments in bulk. That is, you can
+  // set the acknowledgment state of messages in an existing subscription to the
+  // state captured by a snapshot.
   rpc GetSnapshot(GetSnapshotRequest) returns (Snapshot) {
     option (google.api.http) = {
       get: "/v1/{snapshot=projects/*/snapshots/*}"
@@ -592,16 +604,16 @@ service Subscriber {
   }
 
   // Updates an existing snapshot. Snapshots are used in
-  // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a>
-  // operations, which allow
-  // you to manage message acknowledgments in bulk. That is, you can set the
-  // acknowledgment state of messages in an existing subscription to the state
-  // captured by a snapshot.
+  // [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
+  // which allow you to manage message acknowledgments in bulk. That is, you can
+  // set the acknowledgment state of messages in an existing subscription to the
+  // state captured by a snapshot.
   rpc UpdateSnapshot(UpdateSnapshotRequest) returns (Snapshot) {
     option (google.api.http) = {
       patch: "/v1/{snapshot.name=projects/*/snapshots/*}"
       body: "*"
     };
+    option (google.api.method_signature) = "snapshot,update_mask";
   }
 
   // Removes an existing snapshot. Snapshots are used in [Seek]
@@ -635,7 +647,9 @@ service Subscriber {
   }
 }
 
-// A subscription resource.
+// A subscription resource. If none of `push_config` or `bigquery_config` is
+// set, then the subscriber will pull and ack messages using API methods. At
+// most one of these fields may be set.
 message Subscription {
   option (google.api.resource) = {
     type: "pubsub.googleapis.com/Subscription"
@@ -673,21 +687,17 @@ message Subscription {
   ];
 
   // If push delivery is used with this subscription, this field is
-  // used to configure it. Either `pushConfig` or `bigQueryConfig` can be set,
-  // but not both. If both are empty, then the subscriber will pull and ack
-  // messages using API methods.
+  // used to configure it.
   PushConfig push_config = 4;
 
   // If delivery to BigQuery is used with this subscription, this field is
-  // used to configure it. Either `pushConfig` or `bigQueryConfig` can be set,
-  // but not both. If both are empty, then the subscriber will pull and ack
-  // messages using API methods.
+  // used to configure it.
   BigQueryConfig bigquery_config = 18;
 
   // The approximate amount of time (on a best-effort basis) Pub/Sub waits for
   // the subscriber to acknowledge receipt before resending the message. In the
   // interval after the message is delivered and before it is acknowledged, it
-  // is considered to be <i>outstanding</i>. During that time period, the
+  // is considered to be _outstanding_. During that time period, the
   // message will not be redelivered (on a best-effort basis).
   //
   // For pull subscriptions, this value is used as the initial value for the ack
@@ -722,8 +732,8 @@ message Subscription {
   // minutes.
   google.protobuf.Duration message_retention_duration = 8;
 
-  // See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
-  // managing labels</a>.
+  // See [Creating and managing
+  // labels](https://cloud.google.com/pubsub/docs/labels).
   map<string, string> labels = 9;
 
   // If true, messages published with the same `ordering_key` in `PubsubMessage`
@@ -737,7 +747,8 @@ message Subscription {
   // successfully consuming messages from the subscription or is issuing
   // operations on the subscription. If `expiration_policy` is not set, a
   // *default policy* with `ttl` of 31 days will be used. The minimum allowed
-  // value for `expiration_policy.ttl` is 1 day.
+  // value for `expiration_policy.ttl` is 1 day. If `expiration_policy` is set,
+  // but `expiration_policy.ttl` is not set, the subscription never expires.
   ExpirationPolicy expiration_policy = 11;
 
   // An expression written in the Pub/Sub [filter
@@ -795,8 +806,8 @@ message Subscription {
   google.protobuf.Duration topic_message_retention_duration = 17
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. An output-only field indicating whether or not the subscription can receive
-  // messages.
+  // Output only. An output-only field indicating whether or not the
+  // subscription can receive messages.
   State state = 19 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
@@ -912,7 +923,7 @@ message PushConfig {
   // * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
   //
   // For example:
-  // <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+  // `attributes { "x-goog-version": "v1" }`
   map<string, string> attributes = 2;
 
   // An authentication method used by push endpoints to verify the source of
@@ -938,6 +949,11 @@ message BigQueryConfig {
     ACTIVE = 1;
 
     // Cannot write to the BigQuery table because of permission denied errors.
+    // This can happen if
+    // - Pub/Sub SA has not been granted the [appropriate BigQuery IAM
+    // permissions](https://cloud.google.com/pubsub/docs/create-subscription#assign_bigquery_service_account)
+    // - bigquery.googleapis.com API is not enabled for the project
+    // ([instructions](https://cloud.google.com/service-usage/docs/enable-disable))
     PERMISSION_DENIED = 2;
 
     // Cannot write to the BigQuery table because it does not exist.
@@ -948,7 +964,7 @@ message BigQueryConfig {
   }
 
   // The name of the table to which to write data, of the form
-  // {projectId}:{datasetId}.{tableId}
+  // {projectId}.{datasetId}.{tableId}
   string table = 1;
 
   // When true, use the topic's schema as the columns to write to in BigQuery,
@@ -969,8 +985,8 @@ message BigQueryConfig {
   // subscription's backlog.
   bool drop_unknown_fields = 4;
 
-  // Output only. An output-only field that indicates whether or not the subscription can
-  // receive messages.
+  // Output only. An output-only field that indicates whether or not the
+  // subscription can receive messages.
   State state = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
@@ -1117,7 +1133,8 @@ message PullRequest {
 // Response for the `Pull` method.
 message PullResponse {
   // Received Pub/Sub messages. The list will be empty if there are no more
-  // messages available in the backlog. For JSON, the response can be entirely
+  // messages available in the backlog, or if no messages could be returned
+  // before the request timeout. For JSON, the response can be entirely
   // empty. The Pub/Sub system may return fewer than the `maxMessages` requested
   // even if there are more messages available in the backlog.
   repeated ReceivedMessage received_messages = 1;
@@ -1252,31 +1269,38 @@ message StreamingPullResponse {
   // previously received message.
   message AcknowledgeConfirmation {
     // Successfully processed acknowledgement IDs.
-    repeated string ack_ids = 1 [ctype = CORD];
+    repeated string ack_ids = 1;
 
     // List of acknowledgement IDs that were malformed or whose acknowledgement
     // deadline has expired.
-    repeated string invalid_ack_ids = 2 [ctype = CORD];
+    repeated string invalid_ack_ids = 2;
 
     // List of acknowledgement IDs that were out of order.
-    repeated string unordered_ack_ids = 3 [ctype = CORD];
+    repeated string unordered_ack_ids = 3;
+
+    // List of acknowledgement IDs that failed processing with temporary issues.
+    repeated string temporary_failed_ack_ids = 4;
   }
 
   // Acknowledgement IDs sent in one or more previous requests to modify the
   // deadline for a specific message.
   message ModifyAckDeadlineConfirmation {
     // Successfully processed acknowledgement IDs.
-    repeated string ack_ids = 1 [ctype = CORD];
+    repeated string ack_ids = 1;
 
     // List of acknowledgement IDs that were malformed or whose acknowledgement
     // deadline has expired.
-    repeated string invalid_ack_ids = 2 [ctype = CORD];
+    repeated string invalid_ack_ids = 2;
+
+    // List of acknowledgement IDs that failed processing with temporary issues.
+    repeated string temporary_failed_ack_ids = 3;
   }
 
   // Subscription properties sent as part of the response.
   message SubscriptionProperties {
     // True iff exactly once delivery is enabled for this subscription.
     bool exactly_once_delivery_enabled = 1;
+
     // True iff message ordering is enabled for this subscription.
     bool message_ordering_enabled = 2;
   }
@@ -1284,8 +1308,6 @@ message StreamingPullResponse {
   // Received Pub/Sub messages. This will not be empty.
   repeated ReceivedMessage received_messages = 1;
 
-  reserved 2;
-
   // This field will only be set if `enable_exactly_once_delivery` is set to
   // `true`.
   AcknowledgeConfirmation acknowledge_confirmation = 5;
@@ -1303,9 +1325,9 @@ message CreateSnapshotRequest {
   // Required. User-provided name for this snapshot. If the name is not provided
   // in the request, the server will assign a random name for this snapshot on
   // the same project as the subscription. Note that for REST API requests, you
-  // must specify a name.  See the <a
-  // href="https://cloud.google.com/pubsub/docs/admin#resource_names"> resource
-  // name rules</a>. Format is `projects/{project}/snapshots/{snap}`.
+  // must specify a name.  See the [resource name
+  // rules](https://cloud.google.com/pubsub/docs/admin#resource_names). Format
+  // is `projects/{project}/snapshots/{snap}`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "pubsub.googleapis.com/Snapshot" }
@@ -1327,8 +1349,8 @@ message CreateSnapshotRequest {
     }
   ];
 
-  // See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
-  // managing labels</a>.
+  // See [Creating and managing
+  // labels](https://cloud.google.com/pubsub/docs/labels).
   map<string, string> labels = 3;
 }
 

package/build/protos/google/pubsub/v1/schema.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@ import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/protobuf/empty.proto";
+import "google/protobuf/timestamp.proto";
 
 option cc_enable_arenas = true;
 option csharp_namespace = "Google.Cloud.PubSub.V1";
@@ -63,6 +64,41 @@ service SchemaService {
     option (google.api.method_signature) = "parent";
   }
 
+  // Lists all schema revisions for the named schema.
+  rpc ListSchemaRevisions(ListSchemaRevisionsRequest)
+      returns (ListSchemaRevisionsResponse) {
+    option (google.api.http) = {
+      get: "/v1/{name=projects/*/schemas/*}:listRevisions"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Commits a new schema revision to an existing schema.
+  rpc CommitSchema(CommitSchemaRequest) returns (Schema) {
+    option (google.api.http) = {
+      post: "/v1/{name=projects/*/schemas/*}:commit"
+      body: "*"
+    };
+    option (google.api.method_signature) = "name,schema";
+  }
+
+  // Creates a new schema revision that is a copy of the provided revision_id.
+  rpc RollbackSchema(RollbackSchemaRequest) returns (Schema) {
+    option (google.api.http) = {
+      post: "/v1/{name=projects/*/schemas/*}:rollback"
+      body: "*"
+    };
+    option (google.api.method_signature) = "name,revision_id";
+  }
+
+  // Deletes a specific schema revision.
+  rpc DeleteSchemaRevision(DeleteSchemaRevisionRequest) returns (Schema) {
+    option (google.api.http) = {
+      delete: "/v1/{name=projects/*/schemas/*}:deleteRevision"
+    };
+    option (google.api.method_signature) = "name,revision_id";
+  }
+
   // Deletes a schema.
   rpc DeleteSchema(DeleteSchemaRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
@@ -120,6 +156,29 @@ message Schema {
   // the full definition of the schema that is a valid schema definition of
   // the type specified in `type`.
   string definition = 3;
+
+  // Output only. Immutable. The revision ID of the schema.
+  string revision_id = 4 [
+    (google.api.field_behavior) = IMMUTABLE,
+    (google.api.field_behavior) = OUTPUT_ONLY
+  ];
+
+  // Output only. The timestamp that the revision was created.
+  google.protobuf.Timestamp revision_create_time = 6
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// View of Schema object fields to be returned by GetSchema and ListSchemas.
+enum SchemaView {
+  // The default / unset value.
+  // The API will default to the BASIC view.
+  SCHEMA_VIEW_UNSPECIFIED = 0;
+
+  // Include the name and type of the schema, but not the definition.
+  BASIC = 1;
+
+  // Include all Schema object fields.
+  FULL = 2;
 }
 
 // Request for the CreateSchema method.
@@ -148,19 +207,6 @@ message CreateSchemaRequest {
   string schema_id = 3;
 }
 
-// View of Schema object fields to be returned by GetSchema and ListSchemas.
-enum SchemaView {
-  // The default / unset value.
-  // The API will default to the BASIC view.
-  SCHEMA_VIEW_UNSPECIFIED = 0;
-
-  // Include the name and type of the schema, but not the definition.
-  BASIC = 1;
-
-  // Include all Schema object fields.
-  FULL = 2;
-}
-
 // Request for the GetSchema method.
 message GetSchemaRequest {
   // Required. The name of the schema to get.
@@ -171,8 +217,7 @@ message GetSchemaRequest {
   ];
 
   // The set of fields to return in the response. If not set, returns a Schema
-  // with `name` and `type`, but not `definition`. Set to `FULL` to retrieve all
-  // fields.
+  // with all fields filled out. Set to `BASIC` to omit the `definition`.
   SchemaView view = 2;
 }
 
@@ -211,6 +256,83 @@ message ListSchemasResponse {
   string next_page_token = 2;
 }
 
+// Request for the `ListSchemaRevisions` method.
+message ListSchemaRevisionsRequest {
+  // Required. The name of the schema to list revisions for.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+  ];
+
+  // The set of Schema fields to return in the response. If not set, returns
+  // Schemas with `name` and `type`, but not `definition`. Set to `FULL` to
+  // retrieve all fields.
+  SchemaView view = 2;
+
+  // The maximum number of revisions to return per page.
+  int32 page_size = 3;
+
+  // The page token, received from a previous ListSchemaRevisions call.
+  // Provide this to retrieve the subsequent page.
+  string page_token = 4;
+}
+
+// Response for the `ListSchemaRevisions` method.
+message ListSchemaRevisionsResponse {
+  // The revisions of the schema.
+  repeated Schema schemas = 1;
+
+  // A token that can be sent as `page_token` to retrieve the next page.
+  // If this field is empty, there are no subsequent pages.
+  string next_page_token = 2;
+}
+
+// Request for CommitSchema method.
+message CommitSchemaRequest {
+  // Required. The name of the schema we are revising.
+  // Format is `projects/{project}/schemas/{schema}`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+  ];
+
+  // Required. The schema revision to commit.
+  Schema schema = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for the `RollbackSchema` method.
+message RollbackSchemaRequest {
+  // Required. The schema being rolled back with revision id.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+  ];
+
+  // Required. The revision ID to roll back to.
+  // It must be a revision of the same schema.
+  //
+  //   Example: c7cfa2a8
+  string revision_id = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for the `DeleteSchemaRevision` method.
+message DeleteSchemaRevisionRequest {
+  // Required. The name of the schema revision to be deleted, with a revision ID
+  // explicitly included.
+  //
+  // Example: `projects/123/schemas/my-schema@c7cfa2a8`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+  ];
+
+  // Optional. This field is deprecated and should not be used for specifying
+  // the revision ID. The revision ID should be specified via the `name`
+  // parameter.
+  string revision_id = 2
+      [deprecated = true, (google.api.field_behavior) = OPTIONAL];
+}
+
 // Request for the `DeleteSchema` method.
 message DeleteSchemaRequest {
   // Required. Name of the schema to delete.