google-cloud-pubsub 1.8.0 → 2.1.1

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 }

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,6 +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
             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.
@@ -323,7 +330,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.
@@ -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
@@ -566,7 +573,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]
@@ -576,6 +583,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.
         #
@@ -623,6 +659,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
@@ -761,7 +823,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:
         #
@@ -801,6 +864,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
         #
@@ -808,7 +872,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"
@@ -827,7 +891,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"
@@ -847,7 +911,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"
@@ -866,7 +930,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

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

@@ -78,7 +78,7 @@ module Google
         #     end
         #   end
         #
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         def async_publisher
           @async_publisher
@@ -275,7 +275,10 @@ module Google
         #   604,800 seconds (7 days) or less than 600 seconds (10 minutes).
         #   Default is 604,800 seconds (7 days).
         # @param [String] endpoint A URL locating the endpoint to which messages
-        #   should be pushed.
+        #   should be pushed. The parameters `push_config` and `endpoint` should not both be provided.
+        # @param [Google::Cloud::PubSub::Subscription::PushConfig] push_config The configuration for a push delivery
+        #   endpoint that should contain the endpoint, and can contain authentication data (OIDC token authentication).
+        #   The parameters `push_config` and `endpoint` should not both be provided.
         # @param [Hash] labels A hash of user-provided labels associated with
         #   the subscription. You can use these to organize and group your
         #   subscriptions. Label keys and values can be no longer than 63
@@ -320,15 +323,25 @@ module Google
         #   sub = topic.subscribe "my-topic-sub"
         #   sub.name # => "my-topic-sub"
         #
-        # @example Wait 2 minutes for acknowledgement and push all to endpoint:
+        # @example Wait 2 minutes for acknowledgement:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   sub = topic.subscribe "my-topic-sub",
-        #                         deadline: 120,
-        #                         endpoint: "https://example.com/push"
+        #                         deadline: 120
+        #
+        # @example Configure a push endpoint:
+        #   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 Configure a Dead Letter Queues policy:
         #   require "google/cloud/pubsub"
@@ -361,18 +374,40 @@ module Google
         #   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, filter: nil, dead_letter_topic: nil,
-                      dead_letter_max_delivery_attempts: nil, retry_policy: nil
+        def subscribe subscription_name,
+                      deadline: nil,
+                      retain_acked: false,
+                      retention: nil,
+                      endpoint: nil,
+                      push_config: nil,
+                      labels: 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, filter: filter,
-                      dead_letter_max_delivery_attempts: dead_letter_max_delivery_attempts }
+          if push_config && endpoint
+            raise ArgumentError, "endpoint and push_config were both provided. Please provide only one."
+          end
+          push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: endpoint if endpoint
+
+          options = {
+            deadline:                          deadline,
+            retain_acked:                      retain_acked,
+            retention:                         retention,
+            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[:push_config] = push_config.to_grpc if push_config
           options[:retry_policy] = retry_policy.to_grpc if retry_policy
           grpc = service.create_subscription name, subscription_name, options
           Subscription.from_grpc grpc, service
@@ -589,7 +624,7 @@ module Google
         #   end
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         # @example A message can be published using a File object:
         #   require "google/cloud/pubsub"
@@ -601,7 +636,7 @@ module Google
         #   topic.publish_async file
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         # @example Additionally, a message can be published with attributes:
         #   require "google/cloud/pubsub"
@@ -613,7 +648,7 @@ module Google
         #                       foo: :bar, this: :that
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         # @example Ordered messages are supported using ordering_key:
         #   require "google/cloud/pubsub"
@@ -630,7 +665,7 @@ module Google
         #                       ordering_key: "task-key"
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         def publish_async data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &callback
           ensure_service!