google-cloud-pubsub 1.6.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 350813891a25b960230adbe7a22dc40cd847065d368598650a0c663e81d66bc7
-  data.tar.gz: 881a92aec3d136aef23bee956241bf400a5dd203a7f6c0a100e162a4c22c97d0
+  metadata.gz: dfbd62e0e48c406ed08325e5a216f03a0afc4f8319c5ef144fbb6b1fa189e16c
+  data.tar.gz: 31995baf9d81c17e1c867efb5584da5d0be27e1baa3bfa256311e803d43cbfb9
 SHA512:
-  metadata.gz: c364975f01a107d41f1282eecdbec83d25e1d3717abcb45252afebfb64c6d028b9651e9d054bfb5b1caeb6e179045505f79e5faf802c30071f202e7a42e576af
-  data.tar.gz: 7a9d23c2d74e734ad184d6dbb3acabad3868a6dd74b5836d7aa149c4c03edb7c80b414e4d52b2fe8bed9ae4e6794a0634c90c1919a5471196cda408c423f2610
+  metadata.gz: 8d50149459ec7bc696a15785ae7f0d77777d9f95edefb4da0775f9e005c25cd8cfe17d20899649fb17c6fc928eb9e0bbc0baddce26afc773d300c54728b04bd6
+  data.tar.gz: b599664094c01fc88030478e9076ad72a73ceb6bb3aa4b3a64240193694f0d47f6a34bbbd2ab8ce1188c45d6bbd6322d91e91f157362de0a8a6307c002e6084a

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Release History
 
+### 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
+
+* Fix example in Emulator documentation
+* Remove experimental notice from ReceivedMessage#delivery_attempt
+* Wrap example URLs in backticks
+
 ### 1.6.0 / 2020-04-06
 
 #### Features

data/EMULATOR.md

@@ -17,7 +17,7 @@ require "google/cloud/pubsub"
 # Make Pub/Sub use the emulator
 ENV["PUBSUB_EMULATOR_HOST"] = "localhost:8918"
 
-pubsub = Google::Cloud::PubSub.new "emulator-project-id"
+pubsub = Google::Cloud::PubSub.new project_id:"emulator-project-id"
 
 # Get a topic in the current project
 my_topic = pubsub.new_topic "my-topic"

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/received_message.rb

@@ -78,11 +78,6 @@ module Google
         # The first delivery of a given message will have this value as `1`. The value is calculated at best effort and
         # is approximate.
         #
-        # EXPERIMENTAL: This feature is part of a closed alpha release and is available only to whitelisted partners.
-        # This method will return `nil` if a dead letter policy is not set on the subscription. 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 [Integer, nil] A delivery attempt value of `1` or greater, or `nil` if a dead letter policy is not set
         #   on the subscription.
         #

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,19 @@ 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,
+              ack_deadline_seconds:       options[:deadline],
+              retain_acked_messages:      options[:retain_acked],
               message_retention_duration: mrd,
-              labels:                     labels,
-              enable_message_ordering:    message_ordering,
+              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

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"
@@ -188,7 +189,7 @@ module Google
         ##
         # Returns 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`.
         #
         # Makes an API call to retrieve the endpoint value when called on a
         # reference object. See {#reference?}.
@@ -202,7 +203,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".
+        # For example, a Webhook endpoint might use `https://example.com/push`.
         #
         # @param [String] new_endpoint The new endpoint value.
         #
@@ -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

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
@@ -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,29 @@ 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.
@@ -107,9 +109,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 +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
@@ -312,21 +323,22 @@ 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
+      #     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.
@@ -458,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
@@ -467,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.
@@ -653,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
@@ -407,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]
@@ -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.
@@ -725,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.
@@ -814,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
@@ -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
@@ -526,24 +524,24 @@ 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.
           #   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.
@@ -573,6 +571,7 @@ module Google
               filter: nil,
               dead_letter_policy: nil,
               retry_policy: nil,
+              detached: nil,
               options: nil,
               &block
             req = {
@@ -587,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)
@@ -1322,8 +1322,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.
@@ -1411,7 +1411,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

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "1.6.0".freeze
+      VERSION = "1.9.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.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-06 00:00:00.000000000 Z
+date: 2020-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -141,14 +141,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.10'
+        version: '5.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.10'
+        version: '5.14'
 - !ruby/object:Gem::Dependency
   name: minitest-autotest
   requirement: !ruby/object:Gem::Requirement
@@ -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