feat: Add SeekSubscription and Operations to API

Google APIs · copybara-github · commit b601f026f724 · 2021-06-21T14:07:58.000-07:00
PiperOrigin-RevId: 380660182
diff --git a/google/cloud/pubsublite/v1/BUILD.bazel b/google/cloud/pubsublite/v1/BUILD.bazel
@@ -33,6 +33,7 @@ proto_library(
         "//google/api:client_proto",
         "//google/api:field_behavior_proto",
         "//google/api:resource_proto",
+        "//google/longrunning:operations_proto",
         "@com_google_protobuf//:duration_proto",
         "@com_google_protobuf//:empty_proto",
         "@com_google_protobuf//:field_mask_proto",
@@ -126,6 +127,7 @@ go_proto_library(
     protos = [":pubsublite_proto"],
     deps = [
         "//google/api:annotations_go_proto",
+        "//google/longrunning:longrunning_go_proto",
     ],
 )
 
@@ -137,6 +139,9 @@ go_gapic_library(
     service_yaml = "pubsublite_v1.yaml",
     deps = [
         ":pubsublite_go_proto",
+        "//google/longrunning:longrunning_go_proto",
+        "@com_google_cloud_go//longrunning:go_default_library",
+        "@com_google_cloud_go//longrunning/autogen:go_default_library",
         "@io_bazel_rules_go//proto/wkt:duration_go_proto",
     ],
 )
diff --git a/google/cloud/pubsublite/v1/admin.proto b/google/cloud/pubsublite/v1/admin.proto
@@ -21,6 +21,7 @@ import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/pubsublite/v1/common.proto";
+import "google/longrunning/operations.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
 import "google/protobuf/timestamp.proto";
@@ -139,6 +140,38 @@ service AdminService {
     option (google.api.method_signature) = "name";
   }
 
+  // Performs an out-of-band seek for a subscription to a specified target,
+  // which may be timestamps or named positions within the message backlog.
+  // Seek translates these targets to cursors for each partition and
+  // orchestrates subscribers to start consuming messages from these seek
+  // cursors.
+  //
+  // If an operation is returned, the seek has been registered and subscribers
+  // will eventually receive messages from the seek cursors (i.e. eventual
+  // consistency), as long as they are using a minimum supported client library
+  // version and not a system that tracks cursors independently of Pub/Sub Lite
+  // (e.g. Apache Beam, Dataflow, Spark). The seek operation will fail for
+  // unsupported clients.
+  //
+  // If clients would like to know when subscribers react to the seek (or not),
+  // they can poll the operation. The seek operation will succeed and complete
+  // once subscribers are ready to receive messages from the seek cursors for
+  // all partitions of the topic. This means that the seek operation will not
+  // complete until all subscribers come online.
+  //
+  // If the previous seek operation has not yet completed, it will be aborted
+  // and the new invocation of seek will supersede it.
+  rpc SeekSubscription(SeekSubscriptionRequest) returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1/admin/{name=projects/*/locations/*/subscriptions/*}:seek"
+      body: "*"
+    };
+    option (google.longrunning.operation_info) = {
+      response_type: "SeekSubscriptionResponse"
+      metadata_type: "OperationMetadata"
+    };
+  }
+
   // Creates a new reservation.
   rpc CreateReservation(CreateReservationRequest) returns (Reservation) {
     option (google.api.http) = {
@@ -421,6 +454,64 @@ message DeleteSubscriptionRequest {
   ];
 }
 
+// Request for SeekSubscription.
+message SeekSubscriptionRequest {
+  // A named position with respect to the message backlog.
+  enum NamedTarget {
+    // Unspecified named target. Do not use.
+    NAMED_TARGET_UNSPECIFIED = 0;
+
+    // Seek to the oldest retained message.
+    TAIL = 1;
+
+    // Seek past all recently published messages, skipping the entire message
+    // backlog.
+    HEAD = 2;
+  }
+
+  // Required. The name of the subscription to seek.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "pubsublite.googleapis.com/Subscription"
+    }
+  ];
+
+  // The target to seek to. Must be set.
+  oneof target {
+    // Seek to a named position with respect to the message backlog.
+    NamedTarget named_target = 2;
+
+    // Seek to the first message whose publish or event time is greater than or
+    // equal to the specified query time. If no such message can be located,
+    // will seek to the end of the message backlog.
+    TimeTarget time_target = 3;
+  }
+}
+
+// Response for SeekSubscription long running operation.
+message SeekSubscriptionResponse {
+
+}
+
+// Metadata for long running operations.
+message OperationMetadata {
+  // The time the operation was created.
+  google.protobuf.Timestamp create_time = 1;
+
+  // The time the operation finished running. Not set if the operation has not
+  // completed.
+  google.protobuf.Timestamp end_time = 2;
+
+  // Resource path for the target of the operation. For example, targets of
+  // seeks are subscription resources, structured like:
+  // projects/{project_number}/locations/{location}/subscriptions/{subscription_id}
+  string target = 3;
+
+  // Name of the verb executed by the operation.
+  string verb = 4;
+}
+
 // Request for CreateReservation.
 message CreateReservationRequest {
   // Required. The parent location in which to create the reservation.
diff --git a/google/cloud/pubsublite/v1/common.proto b/google/cloud/pubsublite/v1/common.proto
@@ -19,6 +19,7 @@ package google.cloud.pubsublite.v1;
 import "google/api/resource.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/timestamp.proto";
+import "google/api/annotations.proto";
 
 option cc_enable_arenas = true;
 option csharp_namespace = "Google.Cloud.PubSubLite.V1";
diff --git a/google/cloud/pubsublite/v1/publisher.proto b/google/cloud/pubsublite/v1/publisher.proto
@@ -17,6 +17,7 @@ syntax = "proto3";
 package google.cloud.pubsublite.v1;
 
 import "google/cloud/pubsublite/v1/common.proto";
+import "google/api/annotations.proto";
 import "google/api/client.proto";
 
 option cc_enable_arenas = true;
diff --git a/google/cloud/pubsublite/v1/pubsublite_grpc_service_config.json b/google/cloud/pubsublite/v1/pubsublite_grpc_service_config.json
@@ -15,6 +15,14 @@
         },
         {
           "service": "google.cloud.pubsublite.v1.TopicStatsService"
+        },
+        {
+          "service": "google.longrunning.Operations",
+          "method": "GetOperation"
+        },
+        {
+          "service": "google.longrunning.Operations",
+          "method": "ListOperations"
         }
       ],
       "timeout": "600s",
diff --git a/google/cloud/pubsublite/v1/pubsublite_v1.yaml b/google/cloud/pubsublite/v1/pubsublite_v1.yaml
@@ -11,6 +11,22 @@ apis:
 - name: google.cloud.pubsublite.v1.SubscriberService
 - name: google.cloud.pubsublite.v1.TopicStatsService
 
+types:
+- name: google.cloud.pubsublite.v1.OperationMetadata
+- name: google.cloud.pubsublite.v1.SeekSubscriptionResponse
+
+http:
+  rules:
+  - selector: google.longrunning.Operations.CancelOperation
+    post: '/v1/admin/{name=projects/*/locations/*/operations/*}:cancel'
+    body: '*'
+  - selector: google.longrunning.Operations.DeleteOperation
+    delete: '/v1/admin/{name=projects/*/locations/*/operations/*}'
+  - selector: google.longrunning.Operations.GetOperation
+    get: '/v1/admin/{name=projects/*/locations/*/operations/*}'
+  - selector: google.longrunning.Operations.ListOperations
+    get: '/v1/admin/{name=projects/*/locations/*}/operations'
+
 authentication:
   rules:
   - selector: 'google.cloud.pubsublite.v1.AdminService.*'
@@ -37,3 +53,7 @@ authentication:
     oauth:
       canonical_scopes: |-
         https://www.googleapis.com/auth/cloud-platform
+  - selector: 'google.longrunning.Operations.*'
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
diff --git a/google/cloud/pubsublite/v1/subscriber.proto b/google/cloud/pubsublite/v1/subscriber.proto
@@ -18,6 +18,7 @@ package google.cloud.pubsublite.v1;
 
 import "google/api/field_behavior.proto";
 import "google/cloud/pubsublite/v1/common.proto";
+import "google/api/annotations.proto";
 import "google/api/client.proto";
 
 option cc_enable_arenas = true;
