google-cloud-pubsub 1.10.0 → 2.3.0

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

@@ -41,7 +41,7 @@ module Google
       #   subscriber.start
       #
       #   # Shut down the subscriber when ready to stop receiving messages.
-      #   subscriber.stop.wait!
+      #   subscriber.stop!
       #
       # @attr_reader [String] subscription_name The name of the subscription the
       #   messages are pulled from.
@@ -240,7 +240,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def on_error &block
           synchronize do
@@ -276,7 +276,7 @@ module Google
         #   subscriber.last_error #=> nil
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def last_error
           synchronize { @last_error }
@@ -306,6 +306,17 @@ module Google
         # @deprecated Use {#max_outstanding_bytes}.
         alias inventory_bytesize max_outstanding_bytes
 
+        ##
+        # Whether to enforce flow control at the client side only or to enforce it at both the client and
+        # the server. For more details about flow control see https://cloud.google.com/pubsub/docs/pull#config.
+        #
+        # @return [Boolean] `true` when only client side flow control is enforced, `false` when both client and
+        # server side flow control are enforced.
+        #
+        def use_legacy_flow_control?
+          @inventory[:use_legacy_flow_control]
+        end
+
         ##
         # The number of seconds that received messages can be held awaiting processing. Default is 3,600 (1 hour).
         #
@@ -334,7 +345,8 @@ module Google
             limit:                            @inventory[:max_outstanding_messages].fdiv(@streams).ceil,
             bytesize:                         @inventory[:max_outstanding_bytes].fdiv(@streams).ceil,
             extension:                        @inventory[:max_total_lease_duration],
-            max_duration_per_lease_extension: @inventory[:max_duration_per_lease_extension]
+            max_duration_per_lease_extension: @inventory[:max_duration_per_lease_extension],
+            use_legacy_flow_control:          @inventory[:use_legacy_flow_control]
           }
         end
 
@@ -377,6 +389,7 @@ module Google
           @inventory[:max_outstanding_bytes] = Integer(@inventory[:max_outstanding_bytes] || 100_000_000)
           @inventory[:max_total_lease_duration] = Integer(@inventory[:max_total_lease_duration] || 3600)
           @inventory[:max_duration_per_lease_extension] = Integer(@inventory[:max_duration_per_lease_extension] || 0)
+          @inventory[:use_legacy_flow_control] = @inventory[:use_legacy_flow_control] || false
         end
 
         def default_error_callbacks

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

@@ -30,15 +30,18 @@ module Google
 
           include MonitorMixin
 
-          attr_reader :stream, :limit, :bytesize, :extension, :max_duration_per_lease_extension
+          attr_reader :stream, :limit, :bytesize, :extension, :max_duration_per_lease_extension,
+                      :use_legacy_flow_control
 
-          def initialize stream, limit:, bytesize:, extension:, max_duration_per_lease_extension:
+          def initialize stream, limit:, bytesize:, extension:, max_duration_per_lease_extension:,
+                         use_legacy_flow_control:
             super()
             @stream = stream
             @limit = limit
             @bytesize = bytesize
             @extension = extension
             @max_duration_per_lease_extension = max_duration_per_lease_extension
+            @use_legacy_flow_control = use_legacy_flow_control
             @inventory = {}
             @wait_cond = new_cond
           end

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

@@ -271,9 +271,8 @@ module Google
             stop
           rescue GRPC::Cancelled, GRPC::DeadlineExceeded, GRPC::Internal,
                  GRPC::ResourceExhausted, GRPC::Unauthenticated,
-                 GRPC::Unavailable, GRPC::Core::CallError
+                 GRPC::Unavailable
             # Restart the stream with an incremental back for a retriable error.
-            # Also when GRPC raises the internal CallError.
 
             retry
           rescue RestartStream
@@ -364,8 +363,8 @@ module Google
               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
+              req.max_outstanding_messages = @inventory.use_legacy_flow_control ? 0 : @inventory.limit
+              req.max_outstanding_bytes = @inventory.use_legacy_flow_control ? 0 : @inventory.bytesize
             end
           end
 

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

@@ -43,12 +43,19 @@ module Google
       #     received_message.acknowledge!
       #   end
       #
-      #   # Start background threads that will call the block passed to listen.
-      #   subscriber.start
+      #   # Handle exceptions from listener
+      #   subscriber.on_error do |exception|
+      #      puts "Exception: #{exception.class} #{exception.message}"
+      #   end
       #
-      #   # Shut down the subscriber when ready to stop receiving messages.
-      #   subscriber.stop.wait!
+      #   # Gracefully shut down the subscriber
+      #   at_exit do
+      #     subscriber.stop!
+      #   end
       #
+      #   # Start background threads that will call the block passed to listen.
+      #   subscriber.start
+      #   sleep
       class Subscription
         ##
         # @private The Service object.
@@ -346,7 +353,7 @@ module Google
         #   to unset.
         #
         def expires_in= ttl
-          new_expiration_policy = Google::Pubsub::V1::ExpirationPolicy.new ttl: Convert.number_to_duration(ttl)
+          new_expiration_policy = Google::Cloud::PubSub::V1::ExpirationPolicy.new ttl: Convert.number_to_duration(ttl)
 
           update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, expiration_policy: new_expiration_policy
           @grpc = service.update_subscription update_grpc, :expiration_policy
@@ -370,8 +377,8 @@ module Google
         # otherwise `nil`. Dead lettering is done on a best effort basis. The same message might be dead lettered
         # multiple times.
         #
-        # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=} and
-        # {#dead_letter_max_delivery_attempts}.
+        # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=}, {#dead_letter_max_delivery_attempts}
+        # and {#remove_dead_letter_policy}.
         #
         # Makes an API call to retrieve the topic name when called on a reference object. See {#reference?}.
         #
@@ -402,7 +409,8 @@ module Google
         # The operation will fail if the topic does not exist. Users should ensure that there is a subscription attached
         # to this topic since messages published to a topic with no subscriptions are lost.
         #
-        # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=} and {#dead_letter_max_delivery_attempts}.
+        # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=}, {#dead_letter_max_delivery_attempts}
+        # and {#remove_dead_letter_policy}.
         #
         # @param [Topic] new_dead_letter_topic The topic to which dead letter messages for the subscription should be
         #   published.
@@ -434,14 +442,15 @@ module Google
         # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
         # deadline. Note that client libraries may automatically extend ack_deadlines.
         #
-        # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
+        # This field will be honored on a best effort basis. If this parameter is `nil` or `0`, a default value of `5`
+        # is used.
         #
-        # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=} and {#dead_letter_topic}.
+        # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=}, {#dead_letter_topic}
+        # and {#remove_dead_letter_policy}.
         #
         # Makes an API call to retrieve the value when called on a reference object. See {#reference?}.
         #
-        # @return [Integer, nil] A value between 5 and 100, or `nil` if no dead letter policy is configured. If this
-        #   value is 0, a default value of 5 is used.
+        # @return [Integer, nil] A value between `5` and `100`, or `nil` if no dead letter policy is configured.
         #
         # @example
         #   require "google/cloud/pubsub"
@@ -468,10 +477,13 @@ module Google
         #
         # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
         #
-        # The dead letter topic must also be set. See {#dead_letter_topic=} and {#dead_letter_topic}.
+        # The dead letter topic must be set first. See {#dead_letter_topic=}, {#dead_letter_topic} and
+        # {#remove_dead_letter_policy}.
+        #
+        # @param [Integer, nil] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is
+        #   `nil` or `0`, a default value of 5 is used.
         #
-        # @param [Integer] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is 0, a
-        #   default value of 5 is used.
+        # @raise [ArgumentError] if the dead letter topic has not been set. See {#dead_letter_topic=}.
         #
         # @example
         #   require "google/cloud/pubsub"
@@ -496,15 +508,45 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # Removes an existing dead letter policy. A dead letter policy specifies the conditions for dead lettering
+        # messages in the subscription. If a dead letter policy is not set, dead lettering is disabled.
+        #
+        # See {#dead_letter_topic}, {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts} and
+        # {#dead_letter_max_delivery_attempts=}.
+        #
+        # @return [Boolean] `true` if an existing dead letter policy was removed, `false` if no existing dead letter
+        #   policy was present.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
+        #   sub.dead_letter_max_delivery_attempts #=> 10
+        #
+        #   sub.remove_dead_letter_policy
+        #
+        #   sub.dead_letter_topic #=> nil
+        #   sub.dead_letter_max_delivery_attempts #=> nil
+        #
+        def remove_dead_letter_policy
+          ensure_grpc!
+          return false if @grpc.dead_letter_policy.nil?
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: nil
+          @grpc = service.update_subscription update_grpc, :dead_letter_policy
+          true
+        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
@@ -531,9 +573,6 @@ module Google
         # 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
@@ -816,7 +855,8 @@ module Google
         # @param [Integer] streams The number of concurrent streams to open to
         #   pull messages from the subscription. Default is 4. Optional.
         # @param [Hash, Integer] inventory The settings to control how received messages are to be handled by the
-        #   subscriber. When provided as an Integer instead of a Hash only the `limit` will be set. Optional.
+        #   subscriber. When provided as an Integer instead of a Hash only `max_outstanding_messages` will be set.
+        #   Optional.
         #
         #   Hash keys and values may include the following:
         #
@@ -824,6 +864,9 @@ module Google
         #       Default is 1,000. (Note: replaces `:limit`, which is deprecated.)
         #     * `:max_outstanding_bytes` [Integer] The total byte size of received messages to be collected by
         #       subscriber. Default is 100,000,000 (100MB). (Note: replaces `:bytesize`, which is deprecated.)
+        #     * `:use_legacy_flow_control` [Boolean] Disables enforcing flow control settings at the Cloud PubSub
+        #       server and the less accurate method of only enforcing flow control at the client side is used instead.
+        #       Default is false.
         #     * `:max_total_lease_duration` [Integer] The number of seconds that received messages can be held awaiting
         #       processing. Default is 3,600 (1 hour). (Note: replaces `:extension`, which is deprecated.)
         #     * `:max_duration_per_lease_extension` [Integer] The maximum amount of time in seconds for a single lease
@@ -856,6 +899,7 @@ module Google
         #
         #   subscriber = sub.listen do |received_message|
         #     # process message
+        #     puts "Data: #{received_message.message.data}, published at #{received_message.message.published_at}"
         #     received_message.acknowledge!
         #   end
         #
@@ -863,7 +907,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         # @example Configuring to increase concurrent callbacks:
         #   require "google/cloud/pubsub"
@@ -882,7 +926,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         # @example Ordered messages are supported using ordering_key:
         #   require "google/cloud/pubsub"
@@ -902,7 +946,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         # @example Set the maximum amount of time before redelivery if the subscriber fails to extend the deadline:
         #   require "google/cloud/pubsub"
@@ -921,7 +965,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {}, &block
           ensure_service!

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

@@ -22,7 +22,18 @@ module Google
         ##
         # Configuration for a push delivery endpoint.
         #
-        # @example
+        # @example Create a push config:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: "http://example.net/callback"
+        #   push_config.set_oidc_token "service-account@example.net", "audience-header-value"
+        #
+        #   sub = topic.subscribe "my-subscription", push_config: push_config
+        #
+        # @example Read a push config:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
@@ -32,7 +43,7 @@ module Google
         #   sub.push_config.authentication.email #=> "user@example.com"
         #   sub.push_config.authentication.audience #=> "client-12345"
         #
-        # @example Update the push configuration by passing a block:
+        # @example Update a push config:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
@@ -45,14 +56,31 @@ module Google
         #
         class PushConfig
           ##
-          # @private
-          def initialize
+          # Creates a new push configuration.
+          #
+          # @param [String] endpoint A URL locating the endpoint to which messages should be pushed. For
+          #   example, a Webhook endpoint might use `https://example.com/push`.
+          # @param [String] email The service account email to be used for generating the OIDC token.
+          #   The caller must have the `iam.serviceAccounts.actAs` permission for the service account.
+          # @param [String] audience The audience to be used when generating OIDC token. The audience claim identifies
+          #   the recipients that the JWT is intended for. The audience value is a single case-sensitive string. Having
+          #   multiple values (array) for the audience field is not supported. More info about the OIDC JWT token
+          #   audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint`
+          #   URL will be used.
+          #
+          def initialize endpoint: nil, email: nil, audience: nil
             @grpc = Google::Cloud::PubSub::V1::PushConfig.new
+
+            self.endpoint = endpoint unless endpoint.nil?
+
+            raise ArgumentError, "audience provided without email. Authentication is invalid" if audience && !email
+
+            set_oidc_token email, audience if email
           end
 
           ##
-          # A URL locating the endpoint to which messages should be pushed. For
-          # example, a Webhook endpoint might use `https://example.com/push`.
+          # A URL locating the endpoint to which messages should be pushed. For example, a Webhook endpoint might use
+          # `https://example.com/push`.
           #
           # @return [String]
           def endpoint
@@ -60,9 +88,8 @@ module Google
           end
 
           ##
-          # Sets the URL locating the endpoint to which messages should be
-          # pushed. For example, a Webhook endpoint might use
-          # `https://example.com/push`.
+          # Sets the URL locating the endpoint to which messages should be pushed. For example, a Webhook endpoint might
+          # use `https://example.com/push`.
           #
           # @param [String, nil] new_endpoint New URL value
           def endpoint= new_endpoint
@@ -70,8 +97,7 @@ module Google
           end
 
           ##
-          # The authentication method used by push endpoints to verify the
-          # source of push requests.
+          # The authentication method used by push endpoints to verify the source of push requests.
           #
           # @return [OidcToken, nil] An OIDC JWT token if specified, `nil`
           #   otherwise.
@@ -82,8 +108,7 @@ module Google
           end
 
           ##
-          # Sets the authentication method used by push endpoints to verify the
-          # source of push requests.
+          # Sets the authentication method used by push endpoints to verify the source of push requests.
           #
           # @param [OidcToken, nil] new_auth An authentication value.
           def authentication= new_auth
@@ -118,13 +143,12 @@ module Google
           end
 
           ##
-          # The format of the pushed message. This attribute indicates the
-          # version of the data expected by the endpoint. This controls the
-          # shape of the pushed message (i.e., its fields and metadata). The
-          # endpoint version is based on the version of the Pub/Sub API.
+          # The format of the pushed message. This attribute indicates the version of the data expected by the endpoint.
+          # This controls the shape of the pushed message (i.e., its fields and metadata). The endpoint version is based
+          # on the version of the Pub/Sub API.
           #
-          # If not present during the Subscription creation, it will default to
-          # the version of the API used to make such call.
+          # If not present during the Subscription creation, it will default to the version of the API used to make such
+          # call.
           #
           # The possible values for this attribute are:
           #
@@ -182,7 +206,8 @@ module Google
             end
 
             ##
-            # Service account email to be used for generating the OIDC token.
+            # The service account email to be used for generating the OIDC token. The caller must have the
+            # `iam.serviceAccounts.actAs` permission for the service account.
             #
             # @return [String]
             def email
@@ -190,7 +215,8 @@ module Google
             end
 
             ##
-            # Service account email to be used for generating the OIDC token.
+            # Sets the service account email to be used for generating the OIDC token. The caller must have the
+            # `iam.serviceAccounts.actAs` permission for the service account.
             #
             # @param [String] new_email New service account email value.
             def email= new_email
@@ -198,15 +224,10 @@ module Google
             end
 
             ##
-            # Audience to be used when generating OIDC token. The audience claim
-            # identifies the recipients that the JWT is intended for. The
-            # audience value is a single case-sensitive string.
-            #
-            # Having multiple values (array) for the audience field is not
-            # supported.
-            #
-            # More info about the OIDC JWT token audience here:
-            # https://tools.ietf.org/html/rfc7519#section-4.1.3
+            # The audience to be used when generating OIDC token. The audience claim identifies the recipients that
+            # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
+            # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
+            # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
             #
             # @return [String]
             def audience
@@ -214,7 +235,10 @@ module Google
             end
 
             ##
-            # Sets the audience to be used when generating OIDC token.
+            # Sets the audience to be used when generating OIDC token. The audience claim identifies the recipients that
+            # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
+            # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
+            # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
             #
             # @param [String] new_audience New audience value.
             def audience= new_audience