google-cloud-spanner 2.33.0 → 2.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5432cd1029cb3077b9eee5511329297355428098e40afa349d93fb0272b2c092
-  data.tar.gz: a70271c85a8aa155d2e66e50733c388ca7005f4ce924fb921c253e14a98b3d86
+  metadata.gz: d1c4886322cdaa07eb1c80b4a50e92d7e6abda79ac5eacb959680406637aea82
+  data.tar.gz: b1c62c5fcc2ad7ab9f91e948d6c08a6831eddf0560b35e986a4ac9d7bc208976
 SHA512:
-  metadata.gz: 2191fcfe9aad61cca23733bbdfa78f359d10aa140e3fc77a53c3c4dafb5aa72ac99c94ae09437ab4b8080922610d709c634e4023657c706759180202143a00e1
-  data.tar.gz: 682e7a8b1a85c680cfaad9dc4af31c426dad9c80ac19345a034531338a6201173769e161a986a5d53a3382b0fb653f21e9274610800ee931e8d3cd7d72b62c55
+  metadata.gz: aa9eb6272e353e42377b18c610bb143b1f2cea9d5c94313e1748d7bc401260932e9cc8546791d86d0819843350a9e1546cd648aa6df52b2f533d8949c2659fae
+  data.tar.gz: 87a0c66ec2881cea201af2e716c08714bd5b7abeaa44d16efee8f1d25a33cda0773fff894f6075583dd6416dfe9c1233a5fccb9e6f7329734941fa997cb878f2

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 2.34.0 (2026-01-30)
+
+#### Features
+
+* Support request id header feature ([#215](https://github.com/googleapis/ruby-spanner/issues/215)) 
+
 ### 2.33.0 (2025-12-12)
 
 #### Features

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

@@ -14,6 +14,7 @@
 
 
 require "google/cloud/errors"
+require "google/cloud/spanner/spanner_error"
 
 module Google
   module Cloud

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

@@ -0,0 +1,207 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "grpc"
+require "securerandom"
+require "mutex_m"
+require "google/cloud/spanner/errors"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # RequestIdInterceptor is a GRPC interceptor class that captures all the rpc calls
+      # made by the GRPC layer inserting a new Header with a specific ID for debugging purposes.
+      #
+      class RequestIdInterceptor < GRPC::ClientInterceptor
+        @client_id_counter = 0
+        @client_mutex = Mutex.new
+        @channel_id_counter = 0
+        @channel_mutex = Mutex.new
+        @request_id_counter = 0
+        @request_id_mutex = Mutex.new
+        @process_id = nil
+        @process_id_mutex = Mutex.new
+
+        # @private
+        # Gets the next client ID and increments it.
+        #
+        # @return [Integer]
+        private_class_method def self.next_client_id
+          @client_mutex.synchronize do
+            @client_id_counter += 1
+          end
+        end
+
+        # @private
+        # Gets the next channel ID and increments it.
+        #
+        # @return [Integer]
+        private_class_method def self.next_channel_id
+          @channel_mutex.synchronize do
+            @channel_id_counter += 1
+          end
+        end
+
+        # @private
+        # Returns a process ID for the context of the request id header.
+        # A process ID is a Hex encoded 64 bit value
+        #
+        # @param [String, int] process_id A 64 bit value in Hex or Integer format
+        # @return [String]
+        private_class_method def self.get_process_id process_id = nil
+          @process_id_mutex.synchronize do
+            if process_id.nil? || !@process_id.nil?
+              return @process_id ||= (SecureRandom.hex 8)
+            end
+
+            case process_id
+            when Integer
+              if process_id >= 0 && process_id.bit_length <= 64
+                return process_id.to_s(16).rjust(16, "0")
+              end
+            when String
+              if process_id =~ /\A[0-9a-fA-F]{16}\z/
+                return process_id
+              end
+            end
+
+            raise ArgumentError, "process_id must be a 64-bit integer or 16-character hex string"
+          end
+        end
+
+        # Initializes a request_id_interceptor instance.
+        #
+        # @param [String, int] process_id A 64 bit value in Hex or Integer format
+        # @return [Google::Cloud::Spanner::RequestIdInterceptor]
+        def initialize process_id: nil
+          super
+          @version = 1
+          @process_id = self.class.send :get_process_id, process_id
+          @client_id = self.class.send :next_client_id
+          @channel_id = self.class.send :next_channel_id
+          @request_id_counter = 0
+          @request_mutex = Mutex.new
+        end
+
+        # Intercepts a request_response rpc call
+        #
+        # @param [String] method The RPC method name
+        # @param [Google::Protobuf::MessageExts] request The request to be sent to the RPC call
+        # @param [GRPC::ActiveCall::InterceptableView] call An interceptable view object for the call class
+        # @param [Hash] metadata All the metadata to be sent to the RPC call
+        # @return [void]
+        def request_response method:, request:, call:, metadata:, &block
+          # Unused. This is to avoid Rubocop's Lint/UnusedMethodArgument
+          _method = method
+          _request = request
+          _call = call
+          update_metadata_for_call metadata, &block
+        end
+
+        # Intercepts a client_streamer rpc call
+        #
+        # @param [String] method The RPC method name
+        # @param [Google::Protobuf::MessageExts] request The request to be sent to the RPC call
+        # @param [GRPC::ActiveCall::InterceptableView] call An interceptable view object for the call class
+        # @param [Hash] metadata All the metadata to be sent to the RPC call
+        # @return [void]
+        def client_streamer method:, request:, call:, metadata:, &block
+          # Unused. This is to avoid Rubocop's Lint/UnusedMethodArgument
+          _method = method
+          _request = request
+          _call = call
+          update_metadata_for_call metadata, &block
+        end
+
+        # Intercepts a server_streamer rpc call
+        #
+        # @param [String] method The RPC method name
+        # @param [Google::Protobuf::MessageExts] request The request to be sent to the RPC call
+        # @param [GRPC::ActiveCall::InterceptableView] call An interceptable view object for the call class
+        # @param [Hash] metadata All the metadata to be sent to the RPC call
+        # @return [void]
+        def server_streamer method:, request:, call:, metadata:, &block
+          # Unused. This is to avoid Rubocop's Lint/UnusedMethodArgument
+          _method = method
+          _request = request
+          _call = call
+          update_metadata_for_call metadata, &block
+        end
+
+        # Intercepts a bidi_streamer rpc call
+        #
+        # @param [String] method The RPC method name
+        # @param [Google::Protobuf::MessageExts] request The request to be sent to the RPC call
+        # @param [GRPC::ActiveCall::InterceptableView] call An interceptable view object for the call class
+        # @param [Hash] metadata The metadata to be sent to the RPC call
+        # @return [void]
+        def bidi_streamer method:, request:, call:, metadata:, &block
+          # Unused. This is to avoid Rubocop's Lint/UnusedMethodArgument
+          _method = method
+          _request = request
+          _call = call
+          update_metadata_for_call metadata, &block
+        end
+
+        private
+
+        # @private
+        # Inserts the Spanner request id header to the metadata for the RPC call
+        #
+        # @param [Hash] metadata The metadata to be sent to the RPC call
+        # @return [void]
+        def update_metadata_for_call metadata
+          request_id = nil
+          attempt = 1
+
+          if metadata.include? :"x-goog-spanner-request-id"
+            request_id, attempt = get_header_request_id_and_attempt metadata[:"x-goog-spanner-request-id"]
+          else
+            request_id = @request_mutex.synchronize { @request_id_counter += 1 }
+          end
+
+          formatted_request_id = format_request_id request_id, attempt
+          metadata[:"x-goog-spanner-request-id"] = formatted_request_id
+
+          yield
+        rescue StandardError => e
+          e.instance_variable_set :@spanner_header_id, formatted_request_id
+          raise e
+        end
+
+        # @private
+        # Creates the Spanner request id header in the correct format
+        #
+        # @param [String] request_id The request id of the Spanner request
+        # @param [String] attempt The attempt of the current request after retries
+        # @return [String]
+        def format_request_id request_id, attempt
+          "#{@version}.#{@process_id}.#{@client_id}.#{@channel_id}.#{request_id}.#{attempt}"
+        end
+
+        # @private
+        # Parses a request id header and returns the request id and the attempt
+        #
+        # @param [String] header A string representation of a Spanner request ID.
+        # @return [array]
+        def get_header_request_id_and_attempt header
+          _, _, _, _, request_id, attempt = header.split "."
+          [request_id, attempt.to_i + 1]
+        end
+      end
+    end
+  end
+end

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

@@ -36,6 +36,7 @@ module Google
         attr_accessor :lib_name
         attr_accessor :lib_version
         attr_accessor :quota_project
+        attr_accessor :interceptors
         attr_accessor :enable_leader_aware_routing
 
         attr_reader :universe_domain
@@ -51,13 +52,15 @@ module Google
         # @param timeout [::Numeric, nil] Optional. Timeout for Gapic client.
         # @param lib_name [::String, nil] Optional. Library name for headers.
         # @param lib_version [::String, nil] Optional. Library version for headers.
+        # @param interceptors [::Array<GRPC::ClientInterceptor>, nil] Optional.
+        #   An array of interceptors that are run before calls are executed.
         # @param enable_leader_aware_routing [::Boolean, nil] Optional. Whether Leader
         #   Aware Routing should be enabled.
         # @param universe_domain [::String, nil] Optional. The domain of the universe to connect to.
         # @private
         def initialize project, credentials, quota_project: nil,
                        host: nil, timeout: nil, lib_name: nil, lib_version: nil,
-                       enable_leader_aware_routing: nil, universe_domain: nil
+                       interceptors: nil, enable_leader_aware_routing: nil, universe_domain: nil
           @project = project
           @credentials = credentials
           @quota_project = quota_project || (credentials.quota_project_id if credentials.respond_to? :quota_project_id)
@@ -73,6 +76,7 @@ module Google
           @timeout = timeout
           @lib_name = lib_name
           @lib_version = lib_version
+          @interceptors = interceptors
           @enable_leader_aware_routing = enable_leader_aware_routing
         end
 
@@ -106,6 +110,7 @@ module Google
               config.lib_name = lib_name_with_prefix
               config.lib_version = Google::Cloud::Spanner::VERSION
               config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+              config.interceptors = @interceptors if @interceptors
             end
         end
         attr_accessor :mocked_service
@@ -122,6 +127,7 @@ module Google
               config.lib_name = lib_name_with_prefix
               config.lib_version = Google::Cloud::Spanner::VERSION
               config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+              config.interceptors = @interceptors if @interceptors
             end
         end
         attr_accessor :mocked_instances
@@ -138,6 +144,7 @@ module Google
               config.lib_name = lib_name_with_prefix
               config.lib_version = Google::Cloud::Spanner::VERSION
               config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+              config.interceptors = @interceptors if @interceptors
             end
         end
         attr_accessor :mocked_databases

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

@@ -0,0 +1,35 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/errors"
+
+# This is a monkey patch for Google::Cloud::Error to add support for the request_id method
+# to keep this Spanner exclusive method inside the Spanner code.
+# This may be moved into the errors gem itself based on later assessment.
+module Google
+  module Cloud
+    class Error
+      ##
+      # The Spanner header ID if there was an error on the request.
+      #
+      # @return [String, nil]
+      #
+      def request_id
+        return nil unless cause.instance_variable_defined? :@spanner_header_id
+        cause.instance_variable_get :@spanner_header_id
+      end
+    end
+  end
+end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.33.0".freeze
+      VERSION = "2.34.0".freeze
     end
   end
 end

data/lib/google/cloud/spanner.rb

@@ -15,6 +15,8 @@
 
 require "google-cloud-spanner"
 require "google/cloud/spanner/project"
+require "google/cloud/spanner/spanner_error"
+require "google/cloud/spanner/request_id_interceptor"
 require "google/cloud/config"
 require "google/cloud/env"
 
@@ -96,7 +98,7 @@ module Google
       def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
                    endpoint: nil, project: nil, keyfile: nil,
                    emulator_host: nil, lib_name: nil, lib_version: nil,
-                   enable_leader_aware_routing: true, universe_domain: nil
+                   enable_leader_aware_routing: true, universe_domain: nil, process_id: nil
         project_id    ||= project || default_project_id
         scope         ||= configure.scope
         timeout       ||= configure.timeout
@@ -105,6 +107,7 @@ module Google
         credentials   ||= keyfile
         lib_name      ||= configure.lib_name
         lib_version   ||= configure.lib_version
+        interceptors = [RequestIdInterceptor.new(process_id: process_id)]
         universe_domain ||= configure.universe_domain
 
         if emulator_host
@@ -127,7 +130,8 @@ module Google
           Spanner::Service.new(
             project_id, credentials, quota_project: configure.quota_project,
             host: endpoint, timeout: timeout, lib_name: lib_name,
-            lib_version: lib_version, universe_domain: universe_domain,
+            lib_version: lib_version, interceptors: interceptors,
+            universe_domain: universe_domain,
             enable_leader_aware_routing: enable_leader_aware_routing
           ),
           query_options: configure.query_options

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.33.0
+  version: 2.34.0
 platform: ruby
 authors:
 - Mike Moore
@@ -158,12 +158,14 @@ files:
 - lib/google/cloud/spanner/pool.rb
 - lib/google/cloud/spanner/project.rb
 - lib/google/cloud/spanner/range.rb
+- lib/google/cloud/spanner/request_id_interceptor.rb
 - lib/google/cloud/spanner/results.rb
 - lib/google/cloud/spanner/service.rb
 - lib/google/cloud/spanner/session.rb
 - lib/google/cloud/spanner/session_cache.rb
 - lib/google/cloud/spanner/session_creation_options.rb
 - lib/google/cloud/spanner/snapshot.rb
+- lib/google/cloud/spanner/spanner_error.rb
 - lib/google/cloud/spanner/status.rb
 - lib/google/cloud/spanner/transaction.rb
 - lib/google/cloud/spanner/version.rb