feat: Add support for the header id feature

google-cloud-spanner/Gemfile

@@ -23,3 +23,4 @@ gem "simplecov", "~> 0.22"
 gem "solargraph", group: :development, require: false
 gem "yard", "~> 0.9"
 gem "yard-doctest", "~> 0.1.17", group: :development
+gem "mutex_m", "~> 0.3.0"

google-cloud-spanner/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 Spanner
       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 @@ def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
         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 @@ def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
           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

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

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

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

@@ -0,0 +1,137 @@
+# Copyright 2024 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
+      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
+
+        def self.next_client_id
+          @client_mutex.synchronize do
+            @client_id_counter += 1
+          end
+        end
+
+        def self.next_channel_id
+          @channel_mutex.synchronize do
+            @channel_id_counter += 1
+          end
+        end
+
+        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
+
+        def initialize process_id: nil
+          @version = 1
+          @process_id = self.class.get_process_id process_id
+          @client_id = self.class.next_client_id
+          @channel_id = self.class.next_channel_id
+          @request_id_counter = 0
+          @request_mutex = Mutex.new
+        end
+
+        def request_response method:, request:, call:, metadata:
+          update_metadata_for_call call, metadata do
+            yield
+          end
+        end
+
+        def client_streamer method:, request:, call:, metadata:
+          update_metadata_for_call call, metadata do
+            yield
+          end
+        end
+
+        def server_streamer method:, request:, call:, metadata:
+          update_metadata_for_call call, metadata do
+            yield
+          end
+        end
+
+        def bidi_streamer method:, request:, call:, metadata:
+          update_metadata_for_call call, metadata do
+            yield
+          end
+        end
+
+        private
+
+        def validate_process_id process_id
+          value.is_a?(Integer) && value >=0 && value.bit_length <= 64
+        end
+
+        def update_metadata_for_call call, metadata
+          request_id = nil
+          attempt = 1;
+
+          if metadata.include? :"x-goog-spanner-request-id"
+            request_id, attempt = get_header_info 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
+
+          response = yield
+          response
+        rescue => ex
+          ex.instance_variable_set :@spanner_header_id, formatted_request_id
+          raise ex
+        end
+
+        def format_request_id request_id, attempt
+          "#{@version}.#{@process_id}.#{@client_id}.#{@channel_id}.#{request_id}.#{attempt}"
+        end
+
+        def get_header_info header
+          version, process_id, client_id, channel_id, request_id, attempt = header.split('.')
+          [request_id, attempt.to_i + 1];
+        end
+      end
+    end
+  end
+end

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

@@ -36,6 +36,7 @@ class Service
         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 @@ class Service
         # @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 @@ def initialize project, credentials, quota_project: nil,
           @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 @@ def service
               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 @@ def instances
               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 @@ def databases
               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

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

@@ -0,0 +1,34 @@
+# Copyright 2025 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.
+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