google-cloud-spanner 2.33.0 → 2.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5432cd1029cb3077b9eee5511329297355428098e40afa349d93fb0272b2c092
-  data.tar.gz: a70271c85a8aa155d2e66e50733c388ca7005f4ce924fb921c253e14a98b3d86
+  metadata.gz: 7f2092db61c2ca6c7797176db72845ee4889255ed94d641d27ea8b5ac42f62b7
+  data.tar.gz: 3430361284c44739652f9ca1785a902cfccafc813e9b7833df854f0836df98c4
 SHA512:
-  metadata.gz: 2191fcfe9aad61cca23733bbdfa78f359d10aa140e3fc77a53c3c4dafb5aa72ac99c94ae09437ab4b8080922610d709c634e4023657c706759180202143a00e1
-  data.tar.gz: 682e7a8b1a85c680cfaad9dc4af31c426dad9c80ac19345a034531338a6201173769e161a986a5d53a3382b0fb653f21e9274610800ee931e8d3cd7d72b62c55
+  metadata.gz: 4edac28e59ec12727331f7810325de889c71154d28a3fb1dc155ec8d92f2f3b0a5a3e1168cc7a7949befd72bb13da25194107041021872778486ea8744a49c00
+  data.tar.gz: '018fba01b2d4dd8b16483a4a752c7768e8f512637973bdaf080cf7da8e14e20db8cae51ca0843de1b51dffdadfc4c0e5867bbbd94402d12cc8ecb9373416e1fa'

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 2.35.0 (2026-02-23)
+
+#### Features
+
+* propagate transaction tag correctly in all scenarios ([#219](https://github.com/googleapis/ruby-spanner/issues/219)) 
+
+### 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/client.rb

@@ -2227,11 +2227,11 @@ module Google
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
+            transaction_tag = request_options[:transaction_tag] if request_options
             tx = session.create_empty_transaction \
-              exclude_txn_from_change_streams: exclude_txn_from_change_streams, read_lock_mode: read_lock_mode
-            if request_options
-              tx.transaction_tag = request_options[:transaction_tag]
-            end
+              exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+              read_lock_mode: read_lock_mode,
+              transaction_tag: transaction_tag
 
             begin
               Thread.current[IS_TRANSACTION_RUNNING_KEY] = true
@@ -2289,11 +2289,9 @@ module Google
               tx = session.create_empty_transaction(
                 exclude_txn_from_change_streams: exclude_txn_from_change_streams,
                 previous_transaction_id: previous_transaction_id,
-                read_lock_mode: read_lock_mode
+                read_lock_mode: read_lock_mode,
+                transaction_tag: transaction_tag
               )
-              if request_options
-                tx.transaction_tag = request_options[:transaction_tag]
-              end
               retry
             rescue StandardError => e
               # Rollback transaction when handling unexpected error

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/session.rb

@@ -1488,17 +1488,24 @@ module Google
         # @param exclude_txn_from_change_streams [::Boolean] Optional. Defaults to `false`.
         #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
         #   or write transactions from being tracked in change streams.
+        # @param request_options [::Hash, nil] Optional. Common request options.
+        #   Example option: `:priority`.
         # @private
         # @return [::Google::Cloud::Spanner::Transaction]
-        def create_transaction exclude_txn_from_change_streams: false, read_lock_mode: nil
+        def create_transaction exclude_txn_from_change_streams: false, read_lock_mode: nil,
+                               request_options: nil
           route_to_leader = LARHeaders.begin_transaction true
+          request_options = Convert.to_request_options request_options, tag_type: :transaction_tag
+          transaction_tag = request_options[:transaction_tag] if request_options
           tx_grpc = service.begin_transaction path,
                                               route_to_leader: route_to_leader,
                                               exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                                              request_options: request_options,
                                               read_lock_mode: read_lock_mode
           Transaction.from_grpc \
             tx_grpc, self,
-            exclude_txn_from_change_streams: exclude_txn_from_change_streams, read_lock_mode: read_lock_mode
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams, read_lock_mode: read_lock_mode,
+            transaction_tag: transaction_tag
         end
 
         # Creates a new empty transaction wrapper without a server-side object.
@@ -1512,12 +1519,15 @@ module Google
         #   An id of the previous transaction, if this new transaction wrapper is being created
         #   as a part of a retry. Previous transaction id should be added to TransactionOptions
         #   of a new ReadWrite transaction when retry is attempted.
+        # @param transaction_tag [::String, nil] Optional.
+        #   A tag used for statistics collection about this transaction.
         # @private
         # @return [::Google::Cloud::Spanner::Transaction] The new *empty-wrapper* transaction object.
         def create_empty_transaction exclude_txn_from_change_streams: false, previous_transaction_id: nil,
-                                     read_lock_mode: nil
+                                     read_lock_mode: nil, transaction_tag: nil
           Transaction.from_grpc nil, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams,
-previous_transaction_id: previous_transaction_id, read_lock_mode: read_lock_mode
+                                previous_transaction_id: previous_transaction_id, read_lock_mode: read_lock_mode,
+                                transaction_tag: transaction_tag
         end
 
         # If the session is non-multiplexed, keeps the session alive by executing `"SELECT 1"`.

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/transaction.rb

@@ -124,13 +124,17 @@ module Google
         #   An id of the previous transaction, if this new transaction wrapper is being created
         #   as a part of a retry. Previous transaction id should be added to TransactionOptions
         #   of a new ReadWrite transaction when retry is attempted.
+        # @param transaction_tag [::String, nil] Optional.
+        #   A tag used for statistics collection about this transaction.
         # @private
         # @return [::Google::Cloud::Spanner::Transaction]
-        def initialize grpc, session, exclude_txn_from_change_streams, previous_transaction_id: nil, read_lock_mode: nil
+        def initialize grpc, session, exclude_txn_from_change_streams, previous_transaction_id: nil,
+                       read_lock_mode: nil, transaction_tag: nil
           @grpc = grpc
           @session = session
           @exclude_txn_from_change_streams = exclude_txn_from_change_streams
           @read_lock_mode = read_lock_mode
+          @transaction_tag = transaction_tag
 
           # throwing away empty strings for simplicity
           unless previous_transaction_id.nil? || previous_transaction_id.empty?
@@ -1253,12 +1257,14 @@ module Google
         #   An id of the previous transaction, if this new transaction wrapper is being created
         #   as a part of a retry. Previous transaction id should be added to TransactionOptions
         #   of a new ReadWrite transaction when retry is attempted.
+        # @param transaction_tag [::String, nil] Optional.
+        #   A tag used for statistics collection about this transaction.
         # @private
         # @return [::Google::Cloud::Spanner::Transaction]
         def self.from_grpc grpc, session, exclude_txn_from_change_streams: false, previous_transaction_id: nil,
-                           read_lock_mode: nil
+                           read_lock_mode: nil, transaction_tag: nil
           new grpc, session, exclude_txn_from_change_streams, previous_transaction_id: previous_transaction_id,
-read_lock_mode: read_lock_mode
+              read_lock_mode: read_lock_mode, transaction_tag: transaction_tag
         end
 
         ##
@@ -1297,6 +1303,7 @@ read_lock_mode: read_lock_mode
             return if existing_transaction?
             ensure_session!
             route_to_leader = LARHeaders.begin_transaction true
+            request_options = build_request_options request_options
 
             # TODO: [virost@, 2025-10] fix this so it uses tx_selector
             # instead of re-creating it within `Service#begin_transaction`
@@ -1377,7 +1384,7 @@ read_lock_mode: read_lock_mode
 
         ##
         # @private Build request options. If transaction tag is set
-        #   then add into request options.
+        #   then add it to the request options.
         def build_request_options options
           options = Convert.to_request_options options, tag_type: :request_tag
 

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.33.0".freeze
+      VERSION = "2.35.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.35.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