google-cloud-pubsub 1.6.1 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65b27ec5d2bc4fe8948301c5a6d56adb62e436bb0d5da35997cc77bb05e2af59
-  data.tar.gz: 9f7eba965695f834c77cb50f229b2a84ae9d0039528f203b5a0e9db6758e0ae9
+  metadata.gz: 43ee60087a74bfc9938a61cf66f67b937f30c440f921ef83294f5dd2ec8e1079
+  data.tar.gz: 9104bacc161434e7edc1b5553cb0d2f2681ddd6a6a000bf947e212af7dad4df0
 SHA512:
-  metadata.gz: 4cb430ff1c904e6ca3248f024e8b9f82aafc5c28ca90fd45f5265a86df70fc7e48cf68d93e0b71ef4d1946beb2319e898aa6c3c8ca4f78085490b330899f9991
-  data.tar.gz: 8b0af8b3bb8eed0dc11c5e30a61bfb0502758340f5f7062c5f040b371231f58c057bc2d154cdb5a572e81bb674f12c27ed2f734f267a3006f06cd53b2ee6bee8
+  metadata.gz: 4130c4d2961f54b8cf6f1a5957f50d50e37d57bcd56d032df3bbc10497e8788d55e405c69b8570cc24322800af37a35e49daf67755b1652b763b5a9da44b464e
+  data.tar.gz: 5777e0c8d1ca9d56c2a94056971b1e59ccf63e3a1e6dd532f5d223f7a6b8a80f0f0aa29bf1aa984376b48d279bccc3e23aa4ff50940c47b4920c47a6340e5975

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Release History
 
+### 1.10.0 / 2020-07-23
+
+#### Features
+
+* Add Subscription#detach and #detached?
+
+### 1.9.0 / 2020-07-21
+
+#### Features
+
+* Add support for server-side flow control
+
+### 1.8.0 / 2020-06-29
+
+#### Features
+
+* Add Subscription#filter
+
+### 1.7.1 / 2020-05-28
+
+#### Documentation
+
+* Fix a few broken links
+
+### 1.7.0 / 2020-05-21
+
+#### Features
+
+* Add Retry Policy support
+  * Add RetryPolicy
+  * Add retry_policy param to Topic#subscribe
+  * Add Subscription#retry_policy
+  * Add Subscription#retry_policy=
+* Set client-scoped UUID in initial StreamingPullRequest#client_id
+
 ### 1.6.1 / 2020-05-06
 
 #### Documentation

data/TROUBLESHOOTING.md

@@ -24,14 +24,8 @@ improved, *please* create a new issue on GitHub so we can talk about it.
 
   - [New issue][gh-ruby]
 
-Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
-can use the "ruby" channel for general Ruby questions, or use the
-"google-cloud-ruby" channel if you have questions about this gem in particular.
-
 [so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+pubsub
 
-[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+pubsub%22
-
-[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
+[gh-search-ruby]: https://github.com/googleapis/google-cloud-ruby/issues?q=label%3A%22api%3A+pubsub%22
 
-[slack-ruby]: https://gcp-slack.appspot.com/
+[gh-ruby]: https://github.com/googleapis/google-cloud-ruby/issues/new

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

@@ -0,0 +1,90 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/errors"
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # # RetryPolicy
+      #
+      # An immutable Retry Policy value object that specifies how Cloud Pub/Sub retries message delivery.
+      #
+      # Retry delay will be exponential based on provided minimum and maximum backoffs. (See [Exponential
+      # backoff](https://en.wikipedia.org/wiki/Exponential_backoff).)
+      #
+      # Retry Policy 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.
+      #
+      # **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.
+      #
+      # @attr [Numeric] minimum_backoff The minimum delay between consecutive deliveries of a given message. Value
+      #   should be between 0 and 600 seconds. The default value is 10 seconds.
+      # @attr [Numeric] maximum_backoff The maximum delay between consecutive deliveries of a given message. Value
+      #   should be between 0 and 600 seconds. The default value is 600 seconds.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::PubSub.new
+      #
+      #   sub = pubsub.subscription "my-topic-sub"
+      #
+      #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+      #
+      #   sub.retry_policy.minimum_backoff #=> 5
+      #   sub.retry_policy.maximum_backoff #=> 300
+      #
+      class RetryPolicy
+        attr_reader :minimum_backoff, :maximum_backoff
+
+        ##
+        # Creates a new, immutable RetryPolicy value object.
+        #
+        # @attr [Numeric, nil] minimum_backoff The minimum delay between consecutive deliveries of a given message.
+        #   Value should be between 0 and 600 seconds. If `nil` is provided, the default value is 10 seconds.
+        # @attr [Numeric, nil] maximum_backoff The maximum delay between consecutive deliveries of a given message.
+        #   Value should be between 0 and 600 seconds. If `nil` is provided, the default value is 600 seconds.
+        #
+        def initialize minimum_backoff: nil, maximum_backoff: nil
+          @minimum_backoff = minimum_backoff
+          @maximum_backoff = maximum_backoff
+        end
+
+        ##
+        # @private Convert the RetryPolicy to a Google::Cloud::PubSub::V1::RetryPolicy object.
+        def to_grpc
+          Google::Cloud::PubSub::V1::RetryPolicy.new(
+            minimum_backoff: Convert.number_to_duration(minimum_backoff),
+            maximum_backoff: Convert.number_to_duration(maximum_backoff)
+          )
+        end
+
+        ##
+        # @private New RetryPolicy from a Google::Cloud::PubSub::V1::RetryPolicy object.
+        def self.from_grpc grpc
+          new(
+            minimum_backoff: Convert.duration_to_number(grpc.minimum_backoff),
+            maximum_backoff: Convert.duration_to_number(grpc.maximum_backoff)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -19,6 +19,7 @@ require "google/cloud/pubsub/convert"
 require "google/cloud/pubsub/version"
 require "google/cloud/pubsub/v1"
 require "google/gax/errors"
+require "securerandom"
 
 module Google
   module Cloud
@@ -28,6 +29,12 @@ module Google
       # methods.
       class Service
         attr_accessor :project, :credentials, :host, :timeout, :client_config
+        ###
+        # The same client_id is used across all streaming pull connections that are created by this client. This is
+        # intentional, as it indicates to the server that any guarantees, such as message ordering, made for a stream
+        # that is disconnected will be made for the stream that is created to replace it. The attr_accessor allows the
+        # value to be replaced for unit testing.
+        attr_accessor :client_id
 
         ##
         # Creates a new Service instance.
@@ -38,6 +45,7 @@ module Google
           @host = host || V1::PublisherClient::SERVICE_ADDRESS
           @timeout = timeout
           @client_config = client_config || {}
+          @client_id = SecureRandom.uuid.freeze
         end
 
         def channel
@@ -233,21 +241,18 @@ module Google
                             push_endpoint: options[:endpoint],
                             attributes:    (options[:attributes] || {}).to_h
                         end
-          deadline = options[:deadline]
-          retain_acked = options[:retain_acked]
-          mrd = Convert.number_to_duration options[:retention]
-          labels = options[:labels]
-          message_ordering = options[:message_ordering]
           execute do
             subscriber.create_subscription \
               name, topic,
               push_config:                push_config,
-              ack_deadline_seconds:       deadline,
-              retain_acked_messages:      retain_acked,
-              message_retention_duration: mrd,
-              labels:                     labels,
-              enable_message_ordering:    message_ordering,
+              ack_deadline_seconds:       options[:deadline],
+              retain_acked_messages:      options[:retain_acked],
+              message_retention_duration: Convert.number_to_duration(options[:retention]),
+              labels:                     options[:labels],
+              enable_message_ordering:    options[:message_ordering],
+              filter:                     options[:filter],
               dead_letter_policy:         dead_letter_policy(options),
+              retry_policy:               options[:retry_policy],
               options:                    default_options
           end
         end
@@ -260,12 +265,20 @@ module Google
         end
 
         ##
-        # Deletes an existing subscription.
-        # All pending messages in the subscription are immediately dropped.
+        # Deletes an existing subscription. All pending messages in the subscription are immediately dropped.
         def delete_subscription subscription
           execute do
-            subscriber.delete_subscription subscription_path(subscription),
-                                           options: default_options
+            subscriber.delete_subscription subscription_path(subscription), options: default_options
+          end
+        end
+
+        ##
+        # Detaches a subscription from its topic. All messages retained in the subscription are dropped. Subsequent
+        # `Pull` and `StreamingPull` requests will raise `FAILED_PRECONDITION`. If the subscription is a push
+        # subscription, pushes to the endpoint will stop.
+        def detach_subscription subscription
+          execute do
+            publisher.detach_subscription subscription_path(subscription), options: default_options
           end
         end
 

data/lib/google/cloud/pubsub/subscriber/stream.rb

@@ -363,6 +363,9 @@ module Google
               req.stream_ack_deadline_seconds = @subscriber.deadline
               req.modify_deadline_ack_ids += @inventory.ack_ids
               req.modify_deadline_seconds += @inventory.ack_ids.map { @subscriber.deadline }
+              req.client_id = @subscriber.service.client_id
+              req.max_outstanding_messages = @inventory.limit
+              req.max_outstanding_bytes = @inventory.bytesize
             end
           end
 

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

@@ -18,6 +18,7 @@ require "google/cloud/errors"
 require "google/cloud/pubsub/subscription/list"
 require "google/cloud/pubsub/subscription/push_config"
 require "google/cloud/pubsub/received_message"
+require "google/cloud/pubsub/retry_policy"
 require "google/cloud/pubsub/snapshot"
 require "google/cloud/pubsub/subscriber"
 require "google/cloud/pubsub/v1"
@@ -322,7 +323,7 @@ module Google
         # If {#expires_in=} is not set, a *default* value of of 31 days will be
         # used. The minimum allowed value is 1 day.
         #
-        # Makes an API call to retrieve the labels value when called on a
+        # Makes an API call to retrieve the value when called on a
         # reference object. See {#reference?}.
         #
         # @return [Numeric, nil] The expiration duration, or `nil` if unset.
@@ -352,6 +353,18 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # An expression written in the Cloud Pub/Sub filter language. If non-empty, then only {Message} instances whose
+        # `attributes` field matches the filter are delivered on this subscription. If empty, then no messages are
+        # filtered out.
+        #
+        # @return [String] The frozen filter string.
+        #
+        def filter
+          ensure_grpc!
+          @grpc.filter.freeze
+        end
+
         ##
         # Returns the {Topic} to which dead letter messages should be published if a dead letter policy is configured,
         # otherwise `nil`. Dead lettering is done on a best effort basis. The same message might be dead lettered
@@ -483,6 +496,65 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # A policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, 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 [RetryPolicy, nil] The retry policy for the subscription, or `nil`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #
+        #   sub.retry_policy.minimum_backoff #=> 5
+        #   sub.retry_policy.maximum_backoff #=> 300
+        #
+        def retry_policy
+          ensure_grpc!
+          return nil unless @grpc.retry_policy
+          RetryPolicy.from_grpc @grpc.retry_policy
+        end
+
+        ##
+        # Sets a policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, 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.
+        #
+        # @param [RetryPolicy, nil] new_retry_policy A new retry policy for the subscription, or `nil`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #
+        #   sub.retry_policy.minimum_backoff #=> 5
+        #   sub.retry_policy.maximum_backoff #=> 300
+        #
+        def retry_policy= new_retry_policy
+          ensure_grpc!
+          new_retry_policy = new_retry_policy.to_grpc if new_retry_policy
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, retry_policy: new_retry_policy
+          @grpc = service.update_subscription update_grpc, :retry_policy
+        end
+
         ##
         # Whether message ordering has been enabled. When enabled, messages
         # published with the same `ordering_key` will be delivered in the order
@@ -494,7 +566,7 @@ module Google
         #
         # See {Topic#publish_async}, {#listen}, and {Message#ordering_key}.
         #
-        # Makes an API call to retrieve the retain_acked value when called on a
+        # Makes an API call to retrieve the enable_message_ordering value when called on a
         # reference object. See {#reference?}.
         #
         # @return [Boolean]
@@ -504,6 +576,35 @@ module Google
           @grpc.enable_message_ordering
         end
 
+        ##
+        # Whether the subscription is detached from its topic. Detached subscriptions don't receive messages from their
+        # topic and don't retain any backlog. {#pull} and {#listen} (pull and streaming pull) operations will raise
+        # `FAILED_PRECONDITION`. If the subscription is a push subscription (see {#push_config}), pushes to the endpoint
+        # will not be made. The default value is `false`.
+        #
+        # See {Topic#subscribe} and {#detach}.
+        #
+        # Makes an API call to retrieve the value when called on a
+        # reference object. See {#reference?}.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.detach
+        #
+        #   # sleep 120
+        #   sub.detached? #=> true
+        #
+        def detached?
+          ensure_grpc!
+          @grpc.detached
+        end
+
         ##
         # Determines whether the subscription exists in the Pub/Sub service.
         #
@@ -551,6 +652,32 @@ module Google
           true
         end
 
+        ##
+        # Detaches a subscription from its topic. All messages retained in the subscription are dropped. Detached
+        # subscriptions don't receive messages from their topic and don't retain any backlog. Subsequent {#pull} and
+        # {#listen} (pull and streaming pull) operations will raise `FAILED_PRECONDITION`. If the subscription is a push
+        # subscription (see {#push_config}), pushes to the endpoint will stop. It may take a few minutes for the
+        # subscription's detached state to be reflected in subsequent calls to {#detached?}.
+        #
+        # @return [Boolean] Returns `true` if the detach operation was successful.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.detach
+        #
+        #   # sleep 120
+        #   sub.detached? #=> true
+        #
+        def detach
+          ensure_service!
+          service.detach_subscription name
+          true
+        end
+
         ##
         # Pulls messages from the server. Returns an empty list if there are no
         # messages available in the backlog. Raises an ApiError with status

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
@@ -285,6 +286,9 @@ module Google
         #   Managing Labels](https://cloud.google.com/pubsub/docs/labels).
         # @param [Boolean] message_ordering Whether to enable message ordering
         #   on the subscription.
+        # @param [String] filter An expression written in the Cloud Pub/Sub filter language. If non-empty, then only
+        #   {Message} instances whose `attributes` field matches the filter are delivered on this subscription. If
+        #   empty, then no messages are filtered out. Optional.
         # @param [Topic] dead_letter_topic The {Topic} to which dead letter messages for the subscription should be
         #   published. Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
         #   times. The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
@@ -297,6 +301,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,17 +351,30 @@ 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, filter: 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,
+                      labels: labels, message_ordering: message_ordering, filter: filter,
                       dead_letter_max_delivery_attempts: dead_letter_max_delivery_attempts }
+
           options[:dead_letter_topic_name] = dead_letter_topic.name if dead_letter_topic
           if options[:dead_letter_max_delivery_attempts] && !options[:dead_letter_topic_name]
             # 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

@@ -17,6 +17,7 @@ module Google
   module Cloud
   module PubSub
     module V1
+      # A policy constraining the storage of messages published to the topic.
       # @!attribute [rw] allowed_persistence_regions
       #   @return [Array<String>]
       #     A list of IDs of GCP regions where messages that are published to the topic
@@ -67,7 +68,8 @@ module Google
       # @!attribute [rw] attributes
       #   @return [Hash{String => String}]
       #     Attributes for this message. If this field is empty, the message must
-      #     contain non-empty data.
+      #     contain non-empty data. This can be used to filter messages on the
+      #     subscription.
       # @!attribute [rw] message_id
       #   @return [String]
       #     ID of this message, assigned by the server when the message is published.
@@ -173,7 +175,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 +216,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]
@@ -295,13 +308,11 @@ module Google
       #     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,
+      #     An expression written in the Pub/Sub [filter
+      #     language](https://cloud.google.com/pubsub/docs/filtering). 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
@@ -314,16 +325,20 @@ module Google
       #     permission to Acknowledge() messages on this subscription.
       # @!attribute [rw] retry_policy
       #   @return [Google::Cloud::PubSub::V1::RetryPolicy]
-      #     A policy that specifies how Cloud Pub/Sub retries message delivery for this
+      #     A policy that specifies how 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.
+      # @!attribute [rw] detached
+      #   @return [true, false]
+      #     Indicates whether the subscription is detached from its topic. Detached
+      #     subscriptions don't receive messages from their topic and don't retain any
+      #     backlog. `Pull` and `StreamingPull` requests will return
+      #     FAILED_PRECONDITION. If the subscription is a push subscription, pushes to
+      #     the endpoint will not be made.
       class Subscription; end
 
       # A policy that specifies how Cloud Pub/Sub retries message delivery.
@@ -455,8 +470,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
@@ -464,13 +482,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.
@@ -650,6 +665,28 @@ module Google
       #     to the same value so that state associated with the old stream can be
       #     transferred to the new stream. The same client_id should not be used for
       #     different client instances.
+      # @!attribute [rw] max_outstanding_messages
+      #   @return [Integer]
+      #     Flow control settings for the maximum number of outstanding messages. When
+      #     there are `max_outstanding_messages` or more currently sent to the
+      #     streaming pull client that have not yet been acked or nacked, the server
+      #     stops sending more messages. The sending of messages resumes once the
+      #     number of outstanding messages is less than this value. If the value is
+      #     <= 0, there is no limit to the number of outstanding messages. This
+      #     property can only be set on the initial StreamingPullRequest. If it is set
+      #     on a subsequent request, the stream will be aborted with status
+      #     `INVALID_ARGUMENT`.
+      # @!attribute [rw] max_outstanding_bytes
+      #   @return [Integer]
+      #     Flow control settings for the maximum number of outstanding bytes. When
+      #     there are `max_outstanding_bytes` or more worth of messages currently sent
+      #     to the streaming pull client that have not yet been acked or nacked, the
+      #     server will stop sending more messages. The sending of messages resumes
+      #     once the number of outstanding bytes is less than this value. If the value
+      #     is <= 0, there is no limit to the number of outstanding bytes. This
+      #     property can only be set on the initial StreamingPullRequest. If it is set
+      #     on a subsequent request, the stream will be aborted with status
+      #     `INVALID_ARGUMENT`.
       class StreamingPullRequest; end
 
       # Response for the `StreamingPull` method. This response is used to stream

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

@@ -98,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}"
           )
@@ -113,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]
@@ -336,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
@@ -572,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.
@@ -860,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

data/lib/google/cloud/pubsub/v1/publisher_client_config.json

@@ -7,6 +7,7 @@
           "UNAVAILABLE",
           "UNKNOWN"
         ],
+        "non_idempotent2": [],
         "non_idempotent": [
           "UNAVAILABLE"
         ],
@@ -107,6 +108,11 @@
           "timeout_millis": 60000,
           "retry_codes_name": "non_idempotent",
           "retry_params_name": "default"
+        },
+        "DetachSubscription": {
+          "timeout_millis": 60000,
+          "retry_codes_name": "non_idempotent2",
+          "retry_params_name": "default"
         }
       }
     }

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

@@ -510,13 +510,11 @@ module Google
           #   A hash of the same form as `Google::Cloud::PubSub::V1::ExpirationPolicy`
           #   can also be provided.
           # @param filter [String]
-          #   An expression written in the Cloud Pub/Sub filter language. If non-empty,
+          #   An expression written in the Pub/Sub [filter
+          #   language](https://cloud.google.com/pubsub/docs/filtering). 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.
           # @param dead_letter_policy [Google::Cloud::PubSub::V1::DeadLetterPolicy | Hash]
           #   A policy that specifies the conditions for dead lettering messages in
           #   this subscription. If dead_letter_policy is not set, dead lettering
@@ -529,18 +527,21 @@ module Google
           #   A hash of the same form as `Google::Cloud::PubSub::V1::DeadLetterPolicy`
           #   can also be provided.
           # @param retry_policy [Google::Cloud::PubSub::V1::RetryPolicy | Hash]
-          #   A policy that specifies how Cloud Pub/Sub retries message delivery for this
+          #   A policy that specifies how 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.
           #   A hash of the same form as `Google::Cloud::PubSub::V1::RetryPolicy`
           #   can also be provided.
+          # @param detached [true, false]
+          #   Indicates whether the subscription is detached from its topic. Detached
+          #   subscriptions don't receive messages from their topic and don't retain any
+          #   backlog. `Pull` and `StreamingPull` requests will return
+          #   FAILED_PRECONDITION. If the subscription is a push subscription, pushes to
+          #   the endpoint will not be made.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
@@ -570,6 +571,7 @@ module Google
               filter: nil,
               dead_letter_policy: nil,
               retry_policy: nil,
+              detached: nil,
               options: nil,
               &block
             req = {
@@ -584,7 +586,8 @@ module Google
               expiration_policy: expiration_policy,
               filter: filter,
               dead_letter_policy: dead_letter_policy,
-              retry_policy: retry_policy
+              retry_policy: retry_policy,
+              detached: detached
             }.delete_if { |_, v| v.nil? }
             req = Google::Gax::to_proto(req, Google::Cloud::PubSub::V1::Subscription)
             @create_subscription.call(req, options, &block)

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "1.6.1".freeze
+      VERSION = "1.10.0".freeze
     end
 
     Pubsub = PubSub unless const_defined? :Pubsub

data/lib/google/pubsub/v1/pubsub_pb.rb

@@ -73,6 +73,11 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
   add_message "google.pubsub.v1.DeleteTopicRequest" do
     optional :topic, :string, 1
   end
+  add_message "google.pubsub.v1.DetachSubscriptionRequest" do
+    optional :subscription, :string, 1
+  end
+  add_message "google.pubsub.v1.DetachSubscriptionResponse" do
+  end
   add_message "google.pubsub.v1.Subscription" do
     optional :name, :string, 1
     optional :topic, :string, 2
@@ -86,6 +91,7 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
     optional :filter, :string, 12
     optional :dead_letter_policy, :message, 13, "google.pubsub.v1.DeadLetterPolicy"
     optional :retry_policy, :message, 14, "google.pubsub.v1.RetryPolicy"
+    optional :detached, :bool, 15
   end
   add_message "google.pubsub.v1.RetryPolicy" do
     optional :minimum_backoff, :message, 1, "google.protobuf.Duration"
@@ -161,6 +167,8 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
     repeated :modify_deadline_ack_ids, :string, 4
     optional :stream_ack_deadline_seconds, :int32, 5
     optional :client_id, :string, 6
+    optional :max_outstanding_messages, :int64, 7
+    optional :max_outstanding_bytes, :int64, 8
   end
   add_message "google.pubsub.v1.StreamingPullResponse" do
     repeated :received_messages, :message, 1, "google.pubsub.v1.ReceivedMessage"
@@ -228,6 +236,8 @@ module Google::Cloud::PubSub::V1
   ListTopicSnapshotsRequest = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.ListTopicSnapshotsRequest").msgclass
   ListTopicSnapshotsResponse = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.ListTopicSnapshotsResponse").msgclass
   DeleteTopicRequest = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.DeleteTopicRequest").msgclass
+  DetachSubscriptionRequest = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.DetachSubscriptionRequest").msgclass
+  DetachSubscriptionResponse = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.DetachSubscriptionResponse").msgclass
   Subscription = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.Subscription").msgclass
   RetryPolicy = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.RetryPolicy").msgclass
   DeadLetterPolicy = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.pubsub.v1.DeadLetterPolicy").msgclass

data/lib/google/pubsub/v1/pubsub_services_pb.rb

@@ -53,7 +53,7 @@ module Google::Cloud::PubSub::V1
       rpc :GetTopic, GetTopicRequest, Topic
       # Lists matching topics.
       rpc :ListTopics, ListTopicsRequest, ListTopicsResponse
-      # Lists the names of the subscriptions on this topic.
+      # Lists the names of the attached subscriptions on this topic.
       rpc :ListTopicSubscriptions, ListTopicSubscriptionsRequest, ListTopicSubscriptionsResponse
       # 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>
@@ -68,6 +68,11 @@ module Google::Cloud::PubSub::V1
       # configuration or subscriptions. Existing subscriptions to this topic are
       # not deleted, but their `topic` field is set to `_deleted-topic_`.
       rpc :DeleteTopic, DeleteTopicRequest, Google::Protobuf::Empty
+      # 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.
+      rpc :DetachSubscription, DetachSubscriptionRequest, DetachSubscriptionResponse
     end
 
     Stub = Service.rpc_stub_class

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-pubsub
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.10.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-06 00:00:00.000000000 Z
+date: 2020-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -278,6 +278,7 @@ files:
 - lib/google/cloud/pubsub/project.rb
 - lib/google/cloud/pubsub/publish_result.rb
 - lib/google/cloud/pubsub/received_message.rb
+- lib/google/cloud/pubsub/retry_policy.rb
 - lib/google/cloud/pubsub/service.rb
 - lib/google/cloud/pubsub/snapshot.rb
 - lib/google/cloud/pubsub/snapshot/list.rb
@@ -329,7 +330,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.1.3
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Pub/Sub