google-cloud-pubsub 0.20.0 → 2.6.1

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

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# 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
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+#     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,
@@ -14,62 +14,90 @@
 
 
 require "google/cloud/errors"
-require "google/cloud/core/grpc_backoff"
-require "google/pubsub/v1/pubsub_services_pb"
-require "google/iam/v1/iam_policy_services"
-require "google/cloud/core/grpc_utils"
-require "json"
+require "google/cloud/pubsub/credentials"
+require "google/cloud/pubsub/convert"
+require "google/cloud/pubsub/version"
+require "google/cloud/pubsub/v1"
+require "securerandom"
 
 module Google
   module Cloud
-    module Pubsub
+    module PubSub
       ##
-      # @private Represents the gRPC Pub/Sub service, including all the API
-      # methods.
+      # @private Represents the Pub/Sub service API, including IAM mixins.
       class Service
-        attr_accessor :project, :credentials, :host, :retries, :timeout
+        attr_accessor :project
+        attr_accessor :credentials
+        attr_accessor :host
+        attr_accessor :timeout
+        ###
+        # 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.
-        def initialize project, credentials, host: nil, retries: nil,
-                       timeout: nil
+        def initialize project, credentials, host: nil, timeout: nil
           @project = project
           @credentials = credentials
-          @host = host || "pubsub.googleapis.com"
-          @retries = retries
+          @host = host
           @timeout = timeout
-        end
-
-        def creds
-          return credentials if insecure?
-          GRPC::Core::ChannelCredentials.new.compose \
-            GRPC::Core::CallCredentials.new credentials.client.updater_proc
+          @client_id = SecureRandom.uuid.freeze
         end
 
         def subscriber
           return mocked_subscriber if mocked_subscriber
-          @subscriber ||= Google::Pubsub::V1::Subscriber::Stub.new(
-            host, creds, timeout: timeout)
+          @subscriber ||= V1::Subscriber::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
+          end
         end
         attr_accessor :mocked_subscriber
 
         def publisher
           return mocked_publisher if mocked_publisher
-          @publisher ||= Google::Pubsub::V1::Publisher::Stub.new(
-            host, creds, timeout: timeout)
+          @publisher ||= V1::Publisher::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
+          end
         end
         attr_accessor :mocked_publisher
 
         def iam
           return mocked_iam if mocked_iam
-          @iam ||= Google::Iam::V1::IAMPolicy::Stub.new(
-            host, creds, timeout: timeout)
+          @iam ||= V1::IAMPolicy::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+          end
         end
         attr_accessor :mocked_iam
 
-        def insecure?
-          credentials == :this_channel_is_insecure
+        def schemas
+          return mocked_schemas if mocked_schemas
+          @schemas ||= V1::SchemaService::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+          end
         end
+        attr_accessor :mocked_schemas
 
         ##
         # Gets the configuration of a topic.
@@ -78,33 +106,55 @@ module Google
         # If other attributes are added in the future,
         # they will be returned here.
         def get_topic topic_name, options = {}
-          topic_req = Google::Pubsub::V1::GetTopicRequest.new.tap do |r|
-            r.topic = topic_path(topic_name, options)
-          end
-
-          execute { publisher.get_topic topic_req }
+          publisher.get_topic topic: topic_path(topic_name, options)
         end
 
         ##
         # Lists matching topics.
         def list_topics options = {}
-          topics_req = Google::Pubsub::V1::ListTopicsRequest.new.tap do |r|
-            r.project = project_path(options)
-            r.page_token = options[:token] if options[:token]
-            r.page_size = options[:max] if options[:max]
-          end
+          paged_enum = publisher.list_topics project:    project_path(options),
+                                             page_size:  options[:max],
+                                             page_token: options[:token]
 
-          execute { publisher.list_topics topics_req }
+          paged_enum.response
         end
 
         ##
         # Creates the given topic with the given name.
-        def create_topic topic_name, options = {}
-          topic_req = Google::Pubsub::V1::Topic.new.tap do |r|
-            r.name = topic_path(topic_name, options)
+        def create_topic topic_name,
+                         labels: nil,
+                         kms_key_name: nil,
+                         persistence_regions: nil,
+                         schema_name: nil,
+                         message_encoding: nil,
+                         options: {}
+          if persistence_regions
+            message_storage_policy = Google::Cloud::PubSub::V1::MessageStoragePolicy.new(
+              allowed_persistence_regions: Array(persistence_regions)
+            )
+          end
+
+          if schema_name || message_encoding
+            unless schema_name && message_encoding
+              raise ArgumentError, "Schema settings must include both schema_name and message_encoding."
+            end
+            schema_settings = Google::Cloud::PubSub::V1::SchemaSettings.new(
+              schema:   schema_path(schema_name),
+              encoding: message_encoding.to_s.upcase
+            )
           end
 
-          execute { publisher.create_topic topic_req }
+          publisher.create_topic \
+            name:                   topic_path(topic_name, options),
+            labels:                 labels,
+            kms_key_name:           kms_key_name,
+            message_storage_policy: message_storage_policy,
+            schema_settings:        schema_settings
+        end
+
+        def update_topic topic_obj, *fields
+          mask = Google::Protobuf::FieldMask.new paths: fields.map(&:to_s)
+          publisher.update_topic topic: topic_obj, update_mask: mask
         end
 
         ##
@@ -113,11 +163,7 @@ module Google
         # exist. After a topic is deleted, a new topic may be created with the
         # same name.
         def delete_topic topic_name
-          topic_req = Google::Pubsub::V1::DeleteTopicRequest.new.tap do |r|
-            r.topic = topic_path(topic_name)
-          end
-
-          execute { publisher.delete_topic topic_req }
+          publisher.delete_topic topic: topic_path(topic_name)
         end
 
         ##
@@ -126,102 +172,88 @@ module Google
         # The messages parameter is an array of arrays.
         # The first element is the data, second is attributes hash.
         def publish topic, messages
-          publish_req = Google::Pubsub::V1::PublishRequest.new(
-            topic: topic_path(topic),
-            messages: messages.map do |data, attributes|
-              Google::Pubsub::V1::PubsubMessage.new(
-                data: data, attributes: attributes)
-            end
-          )
-
-          execute { publisher.publish publish_req }
+          publisher.publish topic: topic_path(topic), messages: messages
         end
 
         ##
         # Gets the details of a subscription.
         def get_subscription subscription_name, options = {}
-          sub_req = Google::Pubsub::V1::GetSubscriptionRequest.new(
-            subscription: subscription_path(subscription_name, options)
-          )
-
-          execute { subscriber.get_subscription sub_req }
+          subscriber.get_subscription subscription: subscription_path(subscription_name, options)
         end
 
         ##
         # Lists matching subscriptions by project and topic.
         def list_topics_subscriptions topic, options = {}
-          list_params = { topic:     topic_path(topic, options),
-                          page_token: options[:token],
-                          page_size:  options[:max]
-                        }.delete_if { |_, v| v.nil? }
-          list_req = Google::Pubsub::V1::ListTopicSubscriptionsRequest.new \
-            list_params
-
-          execute { publisher.list_topic_subscriptions list_req }
+          publisher.list_topic_subscriptions topic:      topic_path(topic, options),
+                                             page_size:  options[:max],
+                                             page_token: options[:token]
         end
 
         ##
         # Lists matching subscriptions by project.
         def list_subscriptions options = {}
-          list_params = { project:    project_path(options),
-                          page_token: options[:token],
-                          page_size:  options[:max]
-                        }.delete_if { |_, v| v.nil? }
-          list_req = Google::Pubsub::V1::ListSubscriptionsRequest.new(
-            list_params)
+          paged_enum = subscriber.list_subscriptions project:    project_path(options),
+                                                     page_size:  options[:max],
+                                                     page_token: options[:token]
 
-          execute { subscriber.list_subscriptions list_req }
+          paged_enum.response
         end
 
         ##
         # Creates a subscription on a given topic for a given subscriber.
         def create_subscription topic, subscription_name, options = {}
-          sub_params = { name: subscription_path(subscription_name, options),
-                         topic: topic_path(topic),
-                         ack_deadline_seconds: options[:deadline]
-                       }.delete_if { |_, v| v.nil? }
-          sub_req = Google::Pubsub::V1::Subscription.new sub_params
-          if options[:endpoint]
-            sub_req.push_config = Google::Pubsub::V1::PushConfig.new(
-              push_endpoint: options[:endpoint],
-              attributes: (options[:attributes] || {}).to_h)
-          end
+          subscriber.create_subscription \
+            name:                       subscription_path(subscription_name, options),
+            topic:                      topic_path(topic),
+            push_config:                options[:push_config],
+            ack_deadline_seconds:       options[:deadline],
+            retain_acked_messages:      options[:retain_acked],
+            message_retention_duration: Convert.number_to_duration(options[:retention]),
+            labels:                     options[:labels],
+            enable_message_ordering:    options[:message_ordering],
+            filter:                     options[:filter],
+            dead_letter_policy:         dead_letter_policy(options),
+            retry_policy:               options[:retry_policy]
+        end
 
-          execute { subscriber.create_subscription sub_req }
+        def update_subscription subscription_obj, *fields
+          mask = Google::Protobuf::FieldMask.new paths: fields.map(&:to_s)
+          subscriber.update_subscription subscription: subscription_obj, update_mask: mask
         end
 
         ##
-        # Deletes an existing subscription.
-        # All pending messages in the subscription are immediately dropped.
+        # Deletes an existing subscription. All pending messages in the subscription are immediately dropped.
         def delete_subscription subscription
-          del_req = Google::Pubsub::V1::DeleteSubscriptionRequest.new(
-            subscription: subscription_path(subscription)
-          )
+          subscriber.delete_subscription subscription: subscription_path(subscription)
+        end
 
-          execute { subscriber.delete_subscription del_req }
+        ##
+        # Detaches a subscription from its topic. All messages retained in the subscription are dropped. Subsequent
+        # `Pull` and `StreamingPull` requests will raise `FAILED_PRECONDITION`. If the subscription is a push
+        # subscription, pushes to the endpoint will stop.
+        def detach_subscription subscription
+          publisher.detach_subscription subscription: subscription_path(subscription)
         end
 
         ##
         # Pulls a single message from the server.
         def pull subscription, options = {}
-          pull_req = Google::Pubsub::V1::PullRequest.new(
-            subscription: subscription_path(subscription, options),
-            return_immediately: !(!options.fetch(:immediate, true)),
-            max_messages: options.fetch(:max, 100).to_i
-          )
+          max_messages = options.fetch(:max, 100).to_i
+          return_immediately = !(!options.fetch(:immediate, true))
 
-          execute { subscriber.pull pull_req }
+          subscriber.pull subscription:       subscription_path(subscription, options),
+                          max_messages:       max_messages,
+                          return_immediately: return_immediately
+        end
+
+        def streaming_pull request_enum
+          subscriber.streaming_pull request_enum
         end
 
         ##
         # Acknowledges receipt of a message.
         def acknowledge subscription, *ack_ids
-          ack_req = Google::Pubsub::V1::AcknowledgeRequest.new(
-            subscription: subscription_path(subscription),
-            ack_ids: ack_ids
-          )
-
-          execute { subscriber.acknowledge ack_req }
+          subscriber.acknowledge subscription: subscription_path(subscription), ack_ids: ack_ids
         end
 
         ##
@@ -229,81 +261,171 @@ module Google
         def modify_push_config subscription, endpoint, attributes
           # Convert attributes to strings to match the protobuf definition
           attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
-
-          mpc_req = Google::Pubsub::V1::ModifyPushConfigRequest.new(
-            subscription: subscription_path(subscription),
-            push_config: Google::Pubsub::V1::PushConfig.new(
-              push_endpoint: endpoint,
-              attributes: attributes
-            )
+          push_config = Google::Cloud::PubSub::V1::PushConfig.new(
+            push_endpoint: endpoint,
+            attributes:    attributes
           )
 
-          execute { subscriber.modify_push_config mpc_req }
+          subscriber.modify_push_config subscription: subscription_path(subscription),
+                                        push_config:  push_config
         end
 
         ##
         # Modifies the ack deadline for a specific message.
         def modify_ack_deadline subscription, ids, deadline
-          mad_req = Google::Pubsub::V1::ModifyAckDeadlineRequest.new(
-            subscription: subscription_path(subscription),
-            ack_ids: Array(ids),
-            ack_deadline_seconds: deadline
-          )
+          subscriber.modify_ack_deadline subscription:         subscription_path(subscription),
+                                         ack_ids:              Array(ids),
+                                         ack_deadline_seconds: deadline
+        end
 
-          execute { subscriber.modify_ack_deadline mad_req }
+        ##
+        # Lists snapshots by project.
+        def list_snapshots options = {}
+          paged_enum = subscriber.list_snapshots project:    project_path(options),
+                                                 page_size:  options[:max],
+                                                 page_token: options[:token]
+
+          paged_enum.response
         end
 
-        def get_topic_policy topic_name, options = {}
-          get_req = Google::Iam::V1::GetIamPolicyRequest.new(
-            resource: topic_path(topic_name, options)
-          )
+        ##
+        # Creates a snapshot on a given subscription.
+        def create_snapshot subscription, snapshot_name, labels: nil
+          subscriber.create_snapshot name:         snapshot_path(snapshot_name),
+                                     subscription: subscription_path(subscription),
+                                     labels:       labels
+        end
 
-          execute { iam.get_iam_policy get_req }
+        def update_snapshot snapshot_obj, *fields
+          mask = Google::Protobuf::FieldMask.new paths: fields.map(&:to_s)
+          subscriber.update_snapshot snapshot: snapshot_obj, update_mask: mask
         end
 
-        def set_topic_policy topic_name, new_policy, options = {}
-          set_req = Google::Iam::V1::SetIamPolicyRequest.new(
-            resource: topic_path(topic_name, options),
-            policy: new_policy
-          )
+        ##
+        # Deletes an existing snapshot.
+        # All pending messages in the snapshot are immediately dropped.
+        def delete_snapshot snapshot
+          subscriber.delete_snapshot snapshot: snapshot_path(snapshot)
+        end
 
-          execute { iam.set_iam_policy set_req }
+        ##
+        # Adjusts the given subscription to a time or snapshot.
+        def seek subscription, time_or_snapshot
+          if a_time? time_or_snapshot
+            time = Convert.time_to_timestamp time_or_snapshot
+            subscriber.seek subscription: subscription, time: time
+          else
+            time_or_snapshot = time_or_snapshot.name if time_or_snapshot.is_a? Snapshot
+            subscriber.seek subscription: subscription_path(subscription),
+                            snapshot:     snapshot_path(time_or_snapshot)
+          end
         end
 
-        def test_topic_permissions topic_name, permissions, options = {}
-          test_req = Google::Iam::V1::TestIamPermissionsRequest.new(
-            resource: topic_path(topic_name, options),
-            permissions: permissions
+        ##
+        # Lists schemas in the current (or given) project.
+        # @param view [String, Symbol, nil] Possible values:
+        #   * `BASIC` - Include the name and type of the schema, but not the definition.
+        #   * `FULL` - Include all Schema object fields.
+        #
+        def list_schemas view, options = {}
+          schema_view = Google::Cloud::PubSub::V1::SchemaView.const_get view.to_s.upcase
+          paged_enum = schemas.list_schemas parent:     project_path(options),
+                                            view:       schema_view,
+                                            page_size:  options[:max],
+                                            page_token: options[:token]
+
+          paged_enum.response
+        end
+
+        ##
+        # Creates a schema in the current (or given) project.
+        def create_schema schema_id, type, definition, options = {}
+          schema = Google::Cloud::PubSub::V1::Schema.new(
+            type:       type,
+            definition: definition
           )
+          schemas.create_schema parent:    project_path(options),
+                                schema:    schema,
+                                schema_id: schema_id
+        end
 
-          execute { iam.test_iam_permissions test_req }
+        ##
+        # Gets the details of a schema.
+        # @param view [String, Symbol, nil] The set of fields to return in the response. Possible values:
+        #   * `BASIC` - Include the name and type of the schema, but not the definition.
+        #   * `FULL` - Include all Schema object fields.
+        #
+        def get_schema schema_name, view, options = {}
+          schema_view = Google::Cloud::PubSub::V1::SchemaView.const_get view.to_s.upcase
+          schemas.get_schema name: schema_path(schema_name, options),
+                             view: schema_view
         end
 
-        def get_subscription_policy subscription_name, options = {}
-          get_req = Google::Iam::V1::GetIamPolicyRequest.new(
-            resource: subscription_path(subscription_name, options)
+        ##
+        # Delete a schema.
+        def delete_schema schema_name
+          schemas.delete_schema name: schema_path(schema_name)
+        end
+
+        ##
+        # Validate the definition string intended for a schema.
+        def validate_schema type, definition, options = {}
+          schema = Google::Cloud::PubSub::V1::Schema.new(
+            type:       type,
+            definition: definition
           )
+          schemas.validate_schema parent: project_path(options),
+                                  schema: schema
+        end
+
+        ##
+        # Validates a message against a schema.
+        #
+        # @param message_data [String] Message to validate against the provided `schema_spec`.
+        # @param message_encoding [Google::Cloud::PubSub::V1::Encoding] The encoding expected for messages.
+        # @param schema_name [String] Name of the schema against which to validate.
+        # @param project [String] Name of the project if not the default project.
+        # @param type [String] Ad-hoc schema type against which to validate.
+        # @param definition [String] Ad-hoc schema definition against which to validate.
+        #
+        def validate_message message_data, message_encoding, schema_name: nil, project: nil, type: nil, definition: nil
+          if type && definition
+            schema = Google::Cloud::PubSub::V1::Schema.new(
+              type:       type,
+              definition: definition
+            )
+          end
+          schemas.validate_message parent:   project_path(project: project),
+                                   name:     schema_path(schema_name),
+                                   schema:   schema,
+                                   message:  message_data,
+                                   encoding: message_encoding
+        end
+
+        # Helper methods
 
-          execute { iam.get_iam_policy get_req }
+        def get_topic_policy topic_name, options = {}
+          iam.get_iam_policy resource: topic_path(topic_name, options)
         end
 
-        def set_subscription_policy subscription_name, new_policy, options = {}
-          set_req = Google::Iam::V1::SetIamPolicyRequest.new(
-            resource: subscription_path(subscription_name, options),
-            policy: new_policy
-          )
+        def set_topic_policy topic_name, new_policy, options = {}
+          iam.set_iam_policy resource: topic_path(topic_name, options), policy: new_policy
+        end
 
-          execute { iam.set_iam_policy set_req }
+        def test_topic_permissions topic_name, permissions, options = {}
+          iam.test_iam_permissions resource: topic_path(topic_name, options), permissions: permissions
         end
 
-        def test_subscription_permissions subscription_name,
-                                          permissions, options = {}
-          test_req = Google::Iam::V1::TestIamPermissionsRequest.new(
-            resource: subscription_path(subscription_name, options),
-            permissions: permissions
-          )
+        def get_subscription_policy subscription_name, options = {}
+          iam.get_iam_policy resource: subscription_path(subscription_name, options)
+        end
+
+        def set_subscription_policy subscription_name, new_policy, options = {}
+          iam.set_iam_policy resource: subscription_path(subscription_name, options), policy: new_policy
+        end
 
-          execute { iam.test_iam_permissions test_req }
+        def test_subscription_permissions subscription_name, permissions, options = {}
+          iam.test_iam_permissions resource: subscription_path(subscription_name, options), permissions: permissions
         end
 
         def project_path options = {}
@@ -313,28 +435,48 @@ module Google
 
         def topic_path topic_name, options = {}
           return topic_name if topic_name.to_s.include? "/"
-          "#{project_path(options)}/topics/#{topic_name}"
+          "#{project_path options}/topics/#{topic_name}"
         end
 
         def subscription_path subscription_name, options = {}
           return subscription_name if subscription_name.to_s.include? "/"
-          "#{project_path(options)}/subscriptions/#{subscription_name}"
+          "#{project_path options}/subscriptions/#{subscription_name}"
+        end
+
+        def snapshot_path snapshot_name, options = {}
+          return snapshot_name if snapshot_name.nil? || snapshot_name.to_s.include?("/")
+          "#{project_path options}/snapshots/#{snapshot_name}"
+        end
+
+        def schema_path schema_name, options = {}
+          return schema_name if schema_name.nil? || schema_name.to_s.include?("/")
+          "#{project_path options}/schemas/#{schema_name}"
         end
 
         def inspect
-          "#{self.class}(#{@project})"
+          "#<#{self.class.name} (#{@project})>"
         end
 
         protected
 
-        def execute
-          Google::Cloud::Core::GrpcBackoff.new(retries: retries).execute do
-            yield
+        def a_time? obj
+          return false unless obj.respond_to? :to_time
+          # Rails' String#to_time returns nil if the string doesn't parse.
+          return false if obj.to_time.nil?
+          true
+        end
+
+        def dead_letter_policy options
+          return nil unless options[:dead_letter_topic_name]
+          policy = Google::Cloud::PubSub::V1::DeadLetterPolicy.new dead_letter_topic: options[:dead_letter_topic_name]
+          if options[:dead_letter_max_delivery_attempts]
+            policy.max_delivery_attempts = options[:dead_letter_max_delivery_attempts]
           end
-        rescue GRPC::BadStatus => e
-          raise Error.from_error(e)
+          policy
         end
       end
     end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
 end