google-cloud-spanner 1.16.2 → 2.4.0

data/lib/google/cloud/spanner/database/backup_info.rb

@@ -84,17 +84,26 @@ module Google
           end
 
           ##
-          # The backup contains an externally consistent copy of
-          # `source_database` at the timestamp specified by `create_time`.
-          # received.
+          # The timestamp indicating the creation of the backup.
           # @return [Time]
           def create_time
             Convert.timestamp_to_time @grpc.create_time
           end
 
+          ##
+          # The backup contains an externally consistent copy of
+          # `source_database` at the timestamp specified by
+          # the `version_time` received. If no `version_time` was
+          # given during the creation of the backup, the `version_time`
+          # will be the same as the `create_time`.
+          # @return [Time]
+          def version_time
+            Convert.timestamp_to_time @grpc.version_time
+          end
+
           ##
           # @private Creates a new Database::BackupInfo instance from a
-          # Google::Spanner::Admin::Database::V1::BackupInfo.
+          # `Google::Cloud::Spanner::Admin::Database::V1::BackupInfo`.
           def self.from_grpc grpc
             new grpc
           end

data/lib/google/cloud/spanner/database/job.rb

@@ -52,7 +52,7 @@ module Google
         #
         class Job
           ##
-          # @private The Google::Gax::Operation gRPC object.
+          # @private The `Gapic::Operation` gRPC object.
           attr_accessor :grpc
 
           ##
@@ -89,7 +89,7 @@ module Google
             return nil unless done?
             return nil unless @grpc.grpc_op.result == :response
             return nil unless @grpc.results.instance_of? \
-              Google::Spanner::Admin::Database::V1::Database
+              Admin::Database::V1::Database
             Database.from_grpc @grpc.results, service
           end
 
@@ -201,7 +201,7 @@ module Google
           end
 
           ##
-          # @private New Database::Job from a Google::Gax::Operation object.
+          # @private New Database::Job from a `Gapic::Operation` object.
           def self.from_grpc grpc, service
             new.tap do |job|
               job.instance_variable_set :@grpc, grpc

data/lib/google/cloud/spanner/database/job/list.rb

@@ -146,7 +146,7 @@ module Google
             # @private
             #
             # New Database::Job::List from a
-            # Google::Gax::PagedEnumerable<Google::Longrunning::Operation>
+            # `Gapic::PagedEnumerable<Google::Longrunning::Operation>`
             # object. Operation object is a database operation.
             #
             def self.from_grpc grpc, service
@@ -154,7 +154,7 @@ module Google
                 service.databases.instance_variable_get "@operations_client"
               jobs = new(Array(grpc.response.operations).map do |job_grpc|
                 Job.from_grpc \
-                  Google::Gax::Operation.new(job_grpc, operations_client),
+                  Gapic::Operation.new(job_grpc, operations_client),
                   service
               end)
               jobs.grpc = grpc

data/lib/google/cloud/spanner/database/list.rb

@@ -142,7 +142,7 @@ module Google
 
           ##
           # @private New Database::List from a
-          # Google::Spanner::Admin::Database::V1::ListDatabasesResponse
+          # `Google::Cloud::Spanner::Admin::Database::V1::ListDatabasesResponse`
           # object.
           def self.from_grpc grpc, service, instance_id, max = nil
             databases = List.new(Array(grpc.databases).map do |database|

data/lib/google/cloud/spanner/database/restore_info.rb

@@ -52,7 +52,7 @@ module Google
 
           ##
           # @private Creates a new Database::RestoreInfo instance from a
-          # Google::Spanner::Admin::Database::V1::RestoreInfo.
+          # `Google::Cloud::Spanner::Admin::Database::V1::RestoreInfo`
           def self.from_grpc grpc
             new grpc
           end

data/lib/google/cloud/spanner/fields.rb

@@ -372,9 +372,9 @@ module Google
         ##
         # @private
         def to_grpc_type
-          Google::Spanner::V1::Type.new(
+          V1::Type.new(
             code: :STRUCT,
-            struct_type: Google::Spanner::V1::StructType.new(
+            struct_type: V1::StructType.new(
               fields: @grpc_fields
             )
           )
@@ -382,7 +382,7 @@ module Google
 
         ##
         # @private Creates a new Fields instance from a
-        # Google::Spanner::V1::Metadata::Row_type::Fields.
+        # V1::Metadata::Row_type::Fields.
         def self.from_grpc fields
           new([]).tap do |f|
             f.instance_variable_set :@grpc_fields, Array(fields)
@@ -412,18 +412,18 @@ module Google
           if pair.is_a?(Array)
             if pair.count == 2
               if pair.first.is_a?(Integer)
-                Google::Spanner::V1::StructType::Field.new(
+                V1::StructType::Field.new(
                   type: Convert.grpc_type_for_field(pair.last)
                 )
               else
-                Google::Spanner::V1::StructType::Field.new(
+                V1::StructType::Field.new(
                   name: String(pair.first),
                   type: Convert.grpc_type_for_field(pair.last)
                 )
               end
             else
-              Google::Spanner::V1::StructType::Field.new(
-                type: Google::Spanner::V1::Type.new(
+              V1::StructType::Field.new(
+                type: V1::Type.new(
                   code: :ARRAY,
                   array_element_type: Convert.grpc_type_for_field(pair.last)
                 )
@@ -435,7 +435,7 @@ module Google
             unless pair.is_a?(Symbol)
               raise ArgumentError, "type must be a symbol"
             end
-            Google::Spanner::V1::StructType::Field.new(
+            V1::StructType::Field.new(
               type: Convert.grpc_type_for_field(pair)
             )
           end

data/lib/google/cloud/spanner/instance.rb

@@ -342,10 +342,10 @@ module Google
         #   response.
         #
         #   The response returns a list of
-        #   {Google::Longrunning::Operation long-running operations} whose names
+        #  `Google::Longrunning::Operation` long-running operations whose names
         #   are prefixed by a database name within the specified instance.
         #   The long-running operation
-        #   {Google::Longrunning::Operation#metadata metadata} field type
+        #   `Google::Longrunning::Operation#metadata` metadata field type
         #   `metadata.type_url` describes the type of the metadata.
         #
         #   The filter expression must specify the field name,
@@ -603,10 +603,10 @@ module Google
         #   response.
         #
         #   The response returns a list of
-        #   {Google::Longrunning::Operation long-running operations} whose names
+        #   `Google::Longrunning::Operation` long-running operations whose names
         #   are prefixed by a backup name within the specified instance.
         #   The long-running operation
-        #   {Google::Longrunning::Operation#metadata metadata} field type
+        #   `Google::Longrunning::Operation#metadata` metadata field type
         #   `metadata.type_url` describes the type of the metadata.
         #
         #   The filter expression must specify the field name of an operation, a
@@ -856,7 +856,7 @@ module Google
 
         ##
         # @private Creates a new Instance instance from a
-        # Google::Spanner::Admin::Instance::V1::Instance.
+        # `Google::Cloud::Spanner::Admin::Instance::V1::Instance`.
         def self.from_grpc grpc, service
           new grpc, service
         end
@@ -869,13 +869,6 @@ module Google
         def ensure_service!
           raise "Must have active connection to service" unless service
         end
-
-        def instance_config_path name
-          return name if name.to_s.include? "/"
-          Admin::Instance::V1::InstanceAdminClient.instance_config_path(
-            project, name.to_s
-          )
-        end
       end
     end
   end

data/lib/google/cloud/spanner/instance/config.rb

@@ -77,7 +77,7 @@ module Google
 
           ##
           # @private Creates a new Instance::Config instance from a
-          # Google::Spanner::Admin::Instance::V1::InstanceConfig.
+          # `Google::Cloud::Spanner::Admin::Instance::V1::InstanceConfig`.
           def self.from_grpc grpc
             new grpc
           end

data/lib/google/cloud/spanner/instance/config/list.rb

@@ -142,7 +142,7 @@ module Google
 
             ##
             # @private New Instance::Config::List from a
-            # Google::Spanner::Admin::Instance::V1::ListInstanceConfigsResponse
+            # `Google::Cloud::Spanner::Admin::Instance::V1::ListInstanceConfigsResponse`
             # object.
             def self.from_grpc grpc, service, max = nil
               configs = List.new(Array(grpc.instance_configs).map do |config|

data/lib/google/cloud/spanner/instance/job.rb

@@ -54,7 +54,7 @@ module Google
         #
         class Job
           ##
-          # @private The Google::Gax::Operation gRPC object.
+          # @private The `Gapic::Operation` gRPC object.
           attr_accessor :grpc
 
           ##
@@ -219,7 +219,7 @@ module Google
           end
 
           ##
-          # @private New Instance::Job from a Google::Gax::Operation object.
+          # @private New Instance::Job from a `Gapic::Operation` object.
           def self.from_grpc grpc, service
             new.tap do |job|
               job.instance_variable_set :@grpc, grpc

data/lib/google/cloud/spanner/instance/list.rb

@@ -139,7 +139,7 @@ module Google
 
           ##
           # @private New Instance::List from a
-          # Google::Spanner::Admin::Instance::V1::ListInstancesResponse
+          # `Google::Cloud::Spanner::Admin::Instance::V1::ListInstancesResponse`
           # object.
           def self.from_grpc grpc, service, max = nil
             instances = List.new(Array(grpc.instances).map do |instance|

data/lib/google/cloud/spanner/partition.rb

@@ -172,13 +172,13 @@ module Google
           new.tap do |p|
             if data[:execute]
               execute_sql_grpc = \
-                Google::Spanner::V1::ExecuteSqlRequest.decode(
+                V1::ExecuteSqlRequest.decode(
                   Base64.decode64(data[:execute])
                 )
               p.instance_variable_set :@execute, execute_sql_grpc
             end
             if data[:read]
-              read_grpc = Google::Spanner::V1::ReadRequest.decode \
+              read_grpc = V1::ReadRequest.decode \
                 Base64.decode64(data[:read])
               p.instance_variable_set :@read, read_grpc
             end
@@ -194,7 +194,7 @@ module Google
         end
 
         ##
-        # @private New Partition from a Google::Spanner::V1::ExecuteSqlRequest
+        # @private New Partition from a `Google::Cloud::Spanner::V1::ExecuteSqlRequest`
         # object.
         def self.from_execute_sql_grpc grpc
           new.tap do |p|
@@ -203,7 +203,7 @@ module Google
         end
 
         ##
-        # @private New Partition from a Google::Spanner::V1::ReadRequest object.
+        # @private New Partition from a `Google::Cloud::Spanner::V1::ReadRequest` object.
         def self.from_read_grpc grpc
           new.tap do |p|
             p.instance_variable_set :@read, grpc

data/lib/google/cloud/spanner/policy.rb

@@ -159,7 +159,7 @@ module Google
         end
 
         ##
-        # @private Convert the Policy to a Google::Iam::V1::Policy object.
+        # @private Convert the Policy to a `Google::Iam::V1::Policy` object.
         def to_grpc
           Google::Iam::V1::Policy.new(
             etag: etag,
@@ -174,7 +174,7 @@ module Google
         end
 
         ##
-        # @private New Policy from a Google::Iam::V1::Policy object.
+        # @private New Policy from a `Google::Iam::V1::Policy` object.
         def self.from_grpc grpc
           roles = grpc.bindings.each_with_object({}) do |binding, memo|
             memo[binding.role] = binding.members.to_a

data/lib/google/cloud/spanner/results.rb

@@ -41,6 +41,8 @@ module Google
       #   end
       #
       class Results
+        RST_STREAM_INTERNAL_ERROR = "Received RST_STREAM".freeze
+        EOS_INTERNAL_ERROR = "Received unexpected EOS on DATA frame from server".freeze
         ##
         # The read timestamp chosen for single-use snapshots (read-only
         # transactions).
@@ -107,12 +109,24 @@ module Google
           buffer_upper_bound = 10
           chunked_value = nil
           resume_token = nil
+          should_resume_request = false
+          should_retry_request = false
 
           # Cannot call Enumerator#each because it won't return the first
           # value that was already identified when calling Enumerator#peek.
           # Iterate only using Enumerator#next and break on StopIteration.
           loop do
             begin
+              if should_resume_request
+                @enum = resume_request(resume_token)
+                buffered_responses = []
+                should_resume_request = false
+              elsif should_retry_request
+                @enum = retry_request()
+                buffered_responses = []
+                should_retry_request = false
+              end
+
               grpc = @enum.next
               # metadata should be set before the first iteration...
               @metadata ||= grpc.metadata
@@ -143,28 +157,36 @@ module Google
                 # Flush the buffered responses now that they are all handled
                 buffered_responses = []
               end
-            rescue GRPC::Cancelled, GRPC::DeadlineExceeded, GRPC::Internal,
-                   GRPC::ResourceExhausted, GRPC::Unauthenticated,
-                   GRPC::Unavailable, GRPC::Core::CallError => err
-              if resume_token.nil? || resume_token.empty?
-                # Re-raise if the resume_token is not a valid value.
-                # This can happen if the buffer was flushed.
-                raise Google::Cloud::Error.from_error(err)
-              end
+            # TODO: once the generated client throws only Google Cloud errors, remove
+            # the GRPC errors from the rescue block
+            rescue GRPC::Aborted,
+              GRPC::Cancelled,
+              GRPC::DeadlineExceeded,
+              GRPC::Internal,
+              GRPC::ResourceExhausted,
+              GRPC::Unauthenticated,
+              GRPC::Unavailable,
+              GRPC::Core::CallError,
+              Google::Cloud::AbortedError,
+              Google::Cloud::CanceledError,
+              Google::Cloud::DeadlineExceededError,
+              Google::Cloud::InternalError,
+              Google::Cloud::ResourceExhaustedError,
+              Google::Cloud::UnauthenticatedError,
+              Google::Cloud::UnavailableError => err
 
-              # Resume the stream from the last known resume_token
-              if @execute_query_options
-                @enum = @service.execute_streaming_sql \
-                  @session_path, @sql,
-                  @execute_query_options.merge(resume_token: resume_token)
+              if resumable?(resume_token)
+                should_resume_request = true
+              elsif retryable?(err)
+                should_retry_request = true
+              elsif err.is_a?(Google::Cloud::Error)
+                raise err
               else
-                @enum = @service.streaming_read_table \
-                  @session_path, @table, @columns,
-                  @read_options.merge(resume_token: resume_token)
+                raise Google::Cloud::Error.from_error(err)
               end
 
-              # Flush the buffered responses to reset to the resume_token
-              buffered_responses = []
+            # TODO: once the generated client throws only Google Cloud errors, remove
+            # this rescue block (for GRPC::BadStatus)
             rescue GRPC::BadStatus => err
               raise Google::Cloud::Error.from_error(err)
             rescue StopIteration
@@ -198,6 +220,60 @@ module Google
 
         # rubocop:enable all
 
+        ##
+        # @private
+        # Checks if a request can be resumed by inspecting the resume token
+        def resumable? resume_token
+          resume_token && !resume_token.empty?
+        end
+
+        ##
+        # @private
+        # Checks if a request can be retried. This is based on the error returned.
+        # Retryable errors are:
+        #   - Unavailable error
+        #   - Internal EOS error
+        #   - Internal RST_STREAM error
+        def retryable? err
+          err.instance_of?(Google::Cloud::UnavailableError) ||
+            err.instance_of?(GRPC::Unavailable) ||
+            (err.instance_of?(Google::Cloud::InternalError) && err.message.include?(EOS_INTERNAL_ERROR)) ||
+            (err.instance_of?(GRPC::Internal) && err.details.include?(EOS_INTERNAL_ERROR)) ||
+            (err.instance_of?(Google::Cloud::InternalError) && err.message.include?(RST_STREAM_INTERNAL_ERROR)) ||
+            (err.instance_of?(GRPC::Internal) && err.details.include?(RST_STREAM_INTERNAL_ERROR))
+        end
+
+        ##
+        # @private
+        # Resumes a request, by re-executing it with a resume token.
+        def resume_request resume_token
+          if @execute_query_options
+            @service.execute_streaming_sql(
+              @session_path,
+              @sql,
+              @execute_query_options.merge(resume_token: resume_token)
+            )
+          else
+            @service.streaming_read_table(
+              @session_path,
+              @table,
+              @columns,
+              @read_options.merge(resume_token: resume_token)
+            )
+          end
+        end
+
+        ##
+        # @private
+        # Retries a request, by re-executing it from scratch.
+        def retry_request
+          if @execute_query_options
+            @service.execute_streaming_sql @session_path, @sql, @execute_query_options
+          else
+            @service.streaming_read_table @session_path, @table, @columns, @read_options
+          end
+        end
+
         ##
         # @private
         # Get row count from stats. This will be the exact row count for DML
@@ -243,11 +319,11 @@ module Google
         def self.execute_query service, session_path, sql, params: nil,
                                types: nil, transaction: nil,
                                partition_token: nil, seqno: nil,
-                               query_options: nil
+                               query_options: nil, call_options: nil
           execute_query_options = {
             transaction: transaction, params: params, types: types,
             partition_token: partition_token, seqno: seqno,
-            query_options: query_options
+            query_options: query_options, call_options: call_options
           }
           enum = service.execute_streaming_sql session_path, sql,
                                                execute_query_options
@@ -262,10 +338,13 @@ module Google
         # @private
         def self.read service, session_path, table, columns, keys: nil,
                       index: nil, limit: nil, transaction: nil,
-                      partition_token: nil
-          read_options = { keys: keys, index: index, limit: limit,
-                           transaction: transaction,
-                           partition_token: partition_token }
+                      partition_token: nil, call_options: nil
+          read_options = {
+            keys: keys, index: index, limit: limit,
+            transaction: transaction,
+            partition_token: partition_token,
+            call_options: call_options
+          }
           enum = service.streaming_read_table \
             session_path, table, columns, read_options
           from_enum(enum, service).tap do |results|