google-cloud-pubsub 1.4.0 → 1.7.1

data/lib/google/cloud/pubsub/subscription/push_config.rb

@@ -52,7 +52,7 @@ module Google
 
           ##
           # A URL locating the endpoint to which messages should be pushed. For
-          # example, a Webhook endpoint might use "https://example.com/push".
+          # example, a Webhook endpoint might use `https://example.com/push`.
           #
           # @return [String]
           def endpoint
@@ -62,7 +62,7 @@ module Google
           ##
           # Sets the URL locating the endpoint to which messages should be
           # pushed. For example, a Webhook endpoint might use
-          # "https://example.com/push".
+          # `https://example.com/push`.
           #
           # @param [String, nil] new_endpoint New URL value
           def endpoint= new_endpoint

data/lib/google/cloud/pubsub/topic.rb

@@ -19,6 +19,7 @@ require "google/cloud/pubsub/async_publisher"
 require "google/cloud/pubsub/batch_publisher"
 require "google/cloud/pubsub/subscription"
 require "google/cloud/pubsub/policy"
+require "google/cloud/pubsub/retry_policy"
 
 module Google
   module Cloud
@@ -297,6 +298,13 @@ module Google
         #   the subscription's dead letter policy. Dead lettering is done on a best effort basis. The same message might
         #   be dead lettered multiple times. The value must be between 5 and 100. If this parameter is 0, a default
         #   value of 5 is used. The `dead_letter_topic` must also be set.
+        # @param [RetryPolicy] retry_policy A policy that specifies how Cloud Pub/Sub retries message delivery for
+        #   this subscription. If not set, the default retry policy is applied. This generally implies that messages
+        #   will be retried as soon as possible for healthy subscribers. Retry Policy will be triggered on NACKs or
+        #   acknowledgement deadline exceeded events for a given message.
+        #
+        #   **EXPERIMENTAL:** This API might be changed in backward-incompatible ways and is not recommended for
+        #   production use. It is not subject to any SLA or deprecation policy.
         #
         # @return [Google::Cloud::PubSub::Subscription]
         #
@@ -340,8 +348,19 @@ module Google
         #                         dead_letter_topic: dead_letter_topic,
         #                         dead_letter_max_delivery_attempts: 10
         #
+        # @example Configure a Retry Policy:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #   sub = topic.subscribe "my-topic-sub", retry_policy: retry_policy
+        #
         def subscribe subscription_name, deadline: nil, retain_acked: false, retention: nil, endpoint: nil, labels: nil,
-                      message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil
+                      message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil,
+                      retry_policy: nil
           ensure_service!
           options = { deadline: deadline, retain_acked: retain_acked, retention: retention, endpoint: endpoint,
                       labels: labels, message_ordering: message_ordering,
@@ -351,6 +370,7 @@ module Google
             # Service error message "3:Invalid resource name given (name=)." does not identify param.
             raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
           end
+          options[:retry_policy] = retry_policy.to_grpc if retry_policy
           grpc = service.create_subscription name, subscription_name, options
           Subscription.from_grpc grpc, service
         end

data/lib/google/cloud/pubsub/v1/doc/google/pubsub/v1/pubsub.rb

@@ -107,9 +107,9 @@ module Google
       #   @return [Google::Protobuf::FieldMask]
       #     Required. Indicates which fields in the provided topic to update. Must be
       #     specified and non-empty. Note that if `update_mask` contains
-      #     "message_storage_policy" then the new value will be determined based on the
-      #     policy configured at the project or organization level. The
-      #     `message_storage_policy` must not be set in the `topic` provided above.
+      #     "message_storage_policy" but the `message_storage_policy` is not set in
+      #     the `topic` provided above, then the updated value is determined by the
+      #     policy configured at the project or organization level.
       class UpdateTopicRequest; end
 
       # Request for the Publish method.
@@ -173,7 +173,7 @@ module Google
       # Response for the `ListTopicSubscriptions` method.
       # @!attribute [rw] subscriptions
       #   @return [Array<String>]
-      #     The names of the subscriptions that match the request.
+      #     The names of subscriptions attached to the topic specified in the request.
       # @!attribute [rw] next_page_token
       #   @return [String]
       #     If not empty, indicates that there may be more subscriptions that match
@@ -214,6 +214,17 @@ module Google
       #     Format is `projects/{project}/topics/{topic}`.
       class DeleteTopicRequest; end
 
+      # Request for the DetachSubscription method.
+      # @!attribute [rw] subscription
+      #   @return [String]
+      #     Required. The subscription to detach.
+      #     Format is `projects/{project}/subscriptions/{subscription}`.
+      class DetachSubscriptionRequest; end
+
+      # Response for the DetachSubscription method.
+      # Reserved for future use.
+      class DetachSubscriptionResponse; end
+
       # A subscription resource.
       # @!attribute [rw] name
       #   @return [String]
@@ -293,6 +304,15 @@ module Google
       #     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.
+      # @!attribute [rw] filter
+      #   @return [String]
+      #     An expression written in the Cloud Pub/Sub filter language. If non-empty,
+      #     then only `PubsubMessage`s whose `attributes` field matches the filter are
+      #     delivered on this subscription. If empty, then no messages are filtered
+      #     out.
+      #     <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+      #     API might be changed in backward-incompatible ways and is not recommended
+      #     for production use. It is not subject to any SLA or deprecation policy.
       # @!attribute [rw] dead_letter_policy
       #   @return [Google::Cloud::PubSub::V1::DeadLetterPolicy]
       #     A policy that specifies the conditions for dead lettering messages in
@@ -303,11 +323,41 @@ module Google
       #     parent project (i.e.,
       #     service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
       #     permission to Acknowledge() messages on this subscription.
-      #     <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
-      #     API might be changed in backward-incompatible ways and is not recommended
-      #     for production use. It is not subject to any SLA or deprecation policy.
+      # @!attribute [rw] retry_policy
+      #   @return [Google::Cloud::PubSub::V1::RetryPolicy]
+      #     A policy that specifies how Cloud Pub/Sub retries message delivery for this
+      #     subscription.
+      #
+      #     If not set, the default retry policy is applied. This generally implies
+      #     that messages will be retried as soon as possible for healthy subscribers.
+      #     RetryPolicy will be triggered on NACKs or acknowledgement deadline
+      #     exceeded events for a given message.
+      #     <b>EXPERIMENTAL:</b> This API might be changed in backward-incompatible
+      #     ways and is not recommended for production use. It is not subject to any
+      #     SLA or deprecation policy.
       class Subscription; end
 
+      # A policy that specifies how Cloud Pub/Sub retries message delivery.
+      #
+      # Retry delay will be exponential based on provided minimum and maximum
+      # backoffs. https://en.wikipedia.org/wiki/Exponential_backoff.
+      #
+      # RetryPolicy will be triggered on NACKs or acknowledgement deadline exceeded
+      # events for a given message.
+      #
+      # Retry Policy is implemented on a best effort basis. At times, the delay
+      # between consecutive deliveries may not match the configuration. That is,
+      # delay can be more or less than configured backoff.
+      # @!attribute [rw] minimum_backoff
+      #   @return [Google::Protobuf::Duration]
+      #     The minimum delay between consecutive deliveries of a given message.
+      #     Value should be between 0 and 600 seconds. Defaults to 10 seconds.
+      # @!attribute [rw] maximum_backoff
+      #   @return [Google::Protobuf::Duration]
+      #     The maximum delay between consecutive deliveries of a given message.
+      #     Value should be between 0 and 600 seconds. Defaults to 600 seconds.
+      class RetryPolicy; end
+
       # Dead lettering is done on a best effort basis. The same message might be
       # dead lettered multiple times.
       #
@@ -357,7 +407,7 @@ module Google
       # @!attribute [rw] push_endpoint
       #   @return [String]
       #     A URL locating the endpoint to which messages should be pushed.
-      #     For example, a Webhook endpoint might use "https://example.com/push".
+      #     For example, a Webhook endpoint might use `https://example.com/push`.
       # @!attribute [rw] attributes
       #   @return [Hash{String => String}]
       #     Endpoint configuration attributes that can be used to control different
@@ -416,8 +466,11 @@ module Google
       #     The message.
       # @!attribute [rw] delivery_attempt
       #   @return [Integer]
-      #     Delivery attempt counter is 1 + (the sum of number of NACKs and number of
-      #     ack_deadline exceeds) for this message.
+      #     The approximate number of times that Cloud Pub/Sub has attempted to deliver
+      #     the associated message to a subscriber.
+      #
+      #     More precisely, this is 1 + (number of NACKs) +
+      #     (number of ack_deadline exceeds) for this message.
       #
       #     A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
       #     exceeds event is whenever a message is not acknowledged within
@@ -425,13 +478,10 @@ module Google
       #     Subscription.ackDeadlineSeconds, but may get extended automatically by
       #     the client library.
       #
-      #     The first delivery of a given message will have this value as 1. The value
-      #     is calculated at best effort and is approximate.
+      #     Upon the first delivery of a given message, `delivery_attempt` will have a
+      #     value of 1. The value is calculated at best effort and is approximate.
       #
       #     If a DeadLetterPolicy is not set on the subscription, this will be 0.
-      #     <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
-      #     API might be changed in backward-incompatible ways and is not recommended
-      #     for production use. It is not subject to any SLA or deprecation policy.
       class ReceivedMessage; end
 
       # Request for the GetSubscription method.

data/lib/google/cloud/pubsub/v1/publisher_client.rb

@@ -64,7 +64,11 @@ module Google
             "list_topic_subscriptions" => Google::Gax::PageDescriptor.new(
               "page_token",
               "next_page_token",
-              "subscriptions")
+              "subscriptions"),
+            "list_topic_snapshots" => Google::Gax::PageDescriptor.new(
+              "page_token",
+              "next_page_token",
+              "snapshots")
           }.freeze
 
           private_constant :PAGE_DESCRIPTORS
@@ -94,6 +98,12 @@ module Google
 
           private_constant :PROJECT_PATH_TEMPLATE
 
+          SUBSCRIPTION_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
+            "projects/{project}/subscriptions/{subscription}"
+          )
+
+          private_constant :SUBSCRIPTION_PATH_TEMPLATE
+
           TOPIC_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
             "projects/{project}/topics/{topic}"
           )
@@ -109,6 +119,17 @@ module Google
             )
           end
 
+          # Returns a fully-qualified subscription resource name string.
+          # @param project [String]
+          # @param subscription [String]
+          # @return [String]
+          def self.subscription_path project, subscription
+            SUBSCRIPTION_PATH_TEMPLATE.render(
+              :"project" => project,
+              :"subscription" => subscription
+            )
+          end
+
           # Returns a fully-qualified topic resource name string.
           # @param project [String]
           # @param topic [String]
@@ -292,6 +313,14 @@ module Google
                 {'topic' => request.topic}
               end
             )
+            @list_topic_snapshots = Google::Gax.create_api_call(
+              @publisher_stub.method(:list_topic_snapshots),
+              defaults["list_topic_snapshots"],
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'topic' => request.topic}
+              end
+            )
             @delete_topic = Google::Gax.create_api_call(
               @publisher_stub.method(:delete_topic),
               defaults["delete_topic"],
@@ -324,6 +353,14 @@ module Google
                 {'resource' => request.resource}
               end
             )
+            @detach_subscription = Google::Gax.create_api_call(
+              @publisher_stub.method(:detach_subscription),
+              defaults["detach_subscription"],
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'subscription' => request.subscription}
+              end
+            )
           end
 
           # Service calls
@@ -395,9 +432,9 @@ module Google
           # @param update_mask [Google::Protobuf::FieldMask | Hash]
           #   Required. Indicates which fields in the provided topic to update. Must be
           #   specified and non-empty. Note that if `update_mask` contains
-          #   "message_storage_policy" then the new value will be determined based on the
-          #   policy configured at the project or organization level. The
-          #   `message_storage_policy` must not be set in the `topic` provided above.
+          #   "message_storage_policy" but the `message_storage_policy` is not set in
+          #   the `topic` provided above, then the updated value is determined by the
+          #   policy configured at the project or organization level.
           #   A hash of the same form as `Google::Protobuf::FieldMask`
           #   can also be provided.
           # @param options [Google::Gax::CallOptions]
@@ -560,7 +597,7 @@ module Google
             @list_topics.call(req, options, &block)
           end
 
-          # Lists the names of the subscriptions on this topic.
+          # Lists the names of the attached subscriptions on this topic.
           #
           # @param topic [String]
           #   Required. The name of the topic that subscriptions are attached to.
@@ -615,6 +652,66 @@ module Google
             @list_topic_subscriptions.call(req, options, &block)
           end
 
+          # Lists the names of the snapshots on this topic. 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.
+          #
+          # @param topic [String]
+          #   Required. The name of the topic that snapshots are attached to.
+          #   Format is `projects/{project}/topics/{topic}`.
+          # @param page_size [Integer]
+          #   The maximum number of resources contained in the underlying API
+          #   response. If page streaming is performed per-resource, this
+          #   parameter does not affect the return value. If page streaming is
+          #   performed per-page, this determines the maximum number of
+          #   resources in a page.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @yield [result, operation] Access the result along with the RPC operation
+          # @yieldparam result [Google::Gax::PagedEnumerable<String>]
+          # @yieldparam operation [GRPC::ActiveCall::Operation]
+          # @return [Google::Gax::PagedEnumerable<String>]
+          #   An enumerable of String instances.
+          #   See Google::Gax::PagedEnumerable documentation for other
+          #   operations such as per-page iteration or access to the response
+          #   object.
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
+          #   formatted_topic = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
+          #
+          #   # Iterate over all results.
+          #   publisher_client.list_topic_snapshots(formatted_topic).each do |element|
+          #     # Process element.
+          #   end
+          #
+          #   # Or iterate over results one page at a time.
+          #   publisher_client.list_topic_snapshots(formatted_topic).each_page do |page|
+          #     # Process each page at a time.
+          #     page.each do |element|
+          #       # Process element.
+          #     end
+          #   end
+
+          def list_topic_snapshots \
+              topic,
+              page_size: nil,
+              options: nil,
+              &block
+            req = {
+              topic: topic,
+              page_size: page_size
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Cloud::PubSub::V1::ListTopicSnapshotsRequest)
+            @list_topic_snapshots.call(req, options, &block)
+          end
+
           # Deletes the topic with the given name. Returns `NOT_FOUND` if the topic
           # does not exist. After a topic is deleted, a new topic may be created with
           # the same name; this is an entirely new topic with none of the old
@@ -653,8 +750,8 @@ module Google
           # Sets the access control policy on the specified resource. Replaces
           # any existing policy.
           #
-          # Can return Public Errors: NOT_FOUND, INVALID_ARGUMENT and
-          # PERMISSION_DENIED
+          # Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED`
+          # errors.
           #
           # @param resource [String]
           #   REQUIRED: The resource for which the policy is being specified.
@@ -678,11 +775,13 @@ module Google
           #   require "google/cloud/pubsub"
           #
           #   publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
-          #   formatted_resource = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
+          #
+          #   # TODO: Initialize `resource`:
+          #   resource = ''
           #
           #   # TODO: Initialize `policy`:
           #   policy = {}
-          #   response = publisher_client.set_iam_policy(formatted_resource, policy)
+          #   response = publisher_client.set_iam_policy(resource, policy)
 
           def set_iam_policy \
               resource,
@@ -720,8 +819,10 @@ module Google
           #   require "google/cloud/pubsub"
           #
           #   publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
-          #   formatted_resource = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
-          #   response = publisher_client.get_iam_policy(formatted_resource)
+          #
+          #   # TODO: Initialize `resource`:
+          #   resource = ''
+          #   response = publisher_client.get_iam_policy(resource)
 
           def get_iam_policy \
               resource,
@@ -738,7 +839,7 @@ module Google
 
           # Returns permissions that a caller has on the specified resource. If the
           # resource does not exist, this will return an empty set of
-          # permissions, not a NOT_FOUND error.
+          # permissions, not a `NOT_FOUND` error.
           #
           # Note: This operation is designed to be used for building
           # permission-aware UIs and command-line tools, not for authorization
@@ -764,11 +865,13 @@ module Google
           #   require "google/cloud/pubsub"
           #
           #   publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
-          #   formatted_resource = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
+          #
+          #   # TODO: Initialize `resource`:
+          #   resource = ''
           #
           #   # TODO: Initialize `permissions`:
           #   permissions = []
-          #   response = publisher_client.test_iam_permissions(formatted_resource, permissions)
+          #   response = publisher_client.test_iam_permissions(resource, permissions)
 
           def test_iam_permissions \
               resource,
@@ -782,6 +885,40 @@ module Google
             req = Google::Gax::to_proto(req, Google::Iam::V1::TestIamPermissionsRequest)
             @test_iam_permissions.call(req, options, &block)
           end
+
+          # Detaches a subscription from this topic. All messages retained in the
+          # subscription are dropped. Subsequent `Pull` and `StreamingPull` requests
+          # will return FAILED_PRECONDITION. If the subscription is a push
+          # subscription, pushes to the endpoint will stop.
+          #
+          # @param subscription [String]
+          #   Required. The subscription to detach.
+          #   Format is `projects/{project}/subscriptions/{subscription}`.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @yield [result, operation] Access the result along with the RPC operation
+          # @yieldparam result [Google::Cloud::PubSub::V1::DetachSubscriptionResponse]
+          # @yieldparam operation [GRPC::ActiveCall::Operation]
+          # @return [Google::Cloud::PubSub::V1::DetachSubscriptionResponse]
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
+          #   formatted_subscription = Google::Cloud::PubSub::V1::PublisherClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]")
+          #   response = publisher_client.detach_subscription(formatted_subscription)
+
+          def detach_subscription \
+              subscription,
+              options: nil,
+              &block
+            req = {
+              subscription: subscription
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Cloud::PubSub::V1::DetachSubscriptionRequest)
+            @detach_subscription.call(req, options, &block)
+          end
         end
       end
     end