chore(ruby): Add CI workflow to run mock server tests (#603)

* chore(ruby): Add CI workflow to run mock server tests

* fix minitest after run hook to handle failing tests

Author: aakashanandg

.github/workflows/ruby-wrapper-tests.yml

@@ -0,0 +1,60 @@
+name: Ruby Wrapper Tests
+
+on:
+  push:
+    branches:
+        - main
+  pull_request:
+
+jobs:
+  test:
+    name: Test ${{ matrix.os }} (Ruby ${{ matrix.ruby-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        ruby-version: ['3.3']
+
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./spannerlib/wrappers/spannerlib-ruby
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25.x'
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+          working-directory: ./spannerlib/wrappers/spannerlib-ruby
+
+      - name: Build shared library (Linux)
+        if: runner.os == 'Linux'
+        run: bundle exec rake compile:x86_64-linux
+
+      - name: Build shared library (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          ARCH=$(uname -m)
+          if [ "$ARCH" == "arm64" ]; then
+            bundle exec rake compile:aarch64-darwin
+          else
+            bundle exec rake compile:x86_64-darwin
+          fi
+      - name: Build shared library (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          CC=gcc CXX=g++ AR=ar RANLIB=ranlib bundle exec rake compile:x64-mingw32
+
+      - name: Run Tests
+        run: |
+          bundle exec ruby -Ilib -Ispec spec/spannerlib_ruby_spec.rb

spannerlib/wrappers/spannerlib-ruby/lib/spannerlib/ffi.rb

@@ -28,10 +28,9 @@
 module SpannerLib
   extend FFI::Library
 
-  ENV_OVERRIDE = ENV.fetch("SPANNERLIB_PATH", nil)
-
+  # rubocop:disable Metrics/MethodLength
   def self.platform_dir_from_host
-    host_os  = RbConfig::CONFIG["host_os"]
+    host_os = RbConfig::CONFIG["host_os"]
     host_cpu = RbConfig::CONFIG["host_cpu"]
 
     case host_os
@@ -41,16 +40,19 @@ def self.platform_dir_from_host
       host_cpu =~ /arm|aarch64/ ? "aarch64-linux" : "x86_64-linux"
     when /mswin|mingw|cygwin/
       "x64-mingw32"
+    else
+      raise "Unknown OS: #{host_os}"
     end
   end
+  # rubocop:enable Metrics/MethodLength
 
-  # Build list of candidate paths (ordered): env override, platform-specific, any packaged lib, system library
-  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
   def self.library_path
-    if ENV_OVERRIDE && !ENV_OVERRIDE.empty?
-      return ENV_OVERRIDE if File.file?(ENV_OVERRIDE)
+    env_path = ENV.fetch("SPANNERLIB_PATH", nil)
+    if env_path && !env_path.empty?
+      return env_path if File.file?(env_path)
 
-      warn "SPANNERLIB_PATH set to #{ENV_OVERRIDE} but file not found"
+      warn "SPANNERLIB_PATH set to #{env_path} but file not found"
     end
 
     lib_dir = File.expand_path(__dir__)
@@ -62,53 +64,38 @@ def self.library_path
       return candidate if File.exist?(candidate)
     end
 
-    # 3) Any matching packaged binary (first match)
     glob_candidates = Dir.glob(File.join(lib_dir, "*", "spannerlib.#{ext}"))
     return glob_candidates.first unless glob_candidates.empty?
 
-    # 4) Try loading system-wide library (so users who installed shared lib separately can use it)
     begin
-      # Attempt to open system lib name; if succeeds, return bare name so ffi_lib can resolve it
       FFI::DynamicLibrary.open("spannerlib", FFI::DynamicLibrary::RTLD_LAZY | FFI::DynamicLibrary::RTLD_GLOBAL)
       return "spannerlib"
     rescue LoadError
-      # This is intentional. If the system library fails to load,
-      # we'll proceed to the final LoadError with all search paths.
+      # Ignore
     end
 
-    searched = []
-    searched << "ENV SPANNERLIB_PATH=#{ENV_OVERRIDE}" if ENV_OVERRIDE && !ENV_OVERRIDE.empty?
-    searched << File.join(lib_dir, platform || "<detected-platform?>", "spannerlib.#{ext}")
-    searched << File.join(lib_dir, "*", "spannerlib.#{ext}")
-
-    raise LoadError, <<~ERR
-      Could not locate the spannerlib native library. Tried:
-        - #{searched.join("\n  - ")}
-      If you are using the packaged gem, ensure the gem includes lib/spannerlib/<platform>/spannerlib.#{ext}.
-      You can set SPANNERLIB_PATH to the absolute path of the library file, or install a platform-specific native gem.
-    ERR
+    raise LoadError, "Could not locate native library. Checked: #{File.join(lib_dir, platform.to_s)}"
   end
-  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-
+  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
   ffi_lib library_path
 
   class GoString < FFI::Struct
     layout :p,   :pointer,
-           :len, :long
+           :len, :long_long
   end
 
   # GoBytes is the Ruby representation of a Go byte slice
   class GoBytes < FFI::Struct
     layout :p,   :pointer,
-           :len, :long,
-           :cap, :long
+           :len, :long_long,
+           :cap, :long_long
   end
 
   # Message is the common return type for all native functions.
   class Message < FFI::Struct
     layout :pinner,   :long_long,
            :code,     :int,
-           :objectId, :long_long,
+           :remote_id, :long_long,
            :length,   :int,
            :pointer,  :pointer
   end
@@ -188,7 +175,7 @@ def self.ensure_release(message)
 
   def self.handle_object_id_response(message, _func_name)
     ensure_release(message) do
-      MessageHandler.new(message).object_id
+      MessageHandler.new(message).remote_id
     end
   end
 

spannerlib/wrappers/spannerlib-ruby/lib/spannerlib/message_handler.rb

@@ -24,9 +24,9 @@ def initialize(message)
       @message = message
     end
 
-    def object_id
+    def remote_id
       throw_if_error!
-      @message[:objectId]
+      @message[:remote_id]
     end
 
     # Returns the data payload from the message.

spannerlib/wrappers/spannerlib-ruby/spec/mock_server_runner.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# 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.
+
+$stdout.sync = true
+
+require "grpc"
+require "google/cloud/spanner/v1/spanner"
+require "google/spanner/v1/spanner_pb"
+require "google/spanner/v1/spanner_services_pb"
+
+require_relative "mock_server/spanner_mock_server"
+
+Signal.trap("TERM") do
+  exit!(0) # "exit skips cleanup hooks and prevents gRPC segfaults
+end
+
+begin
+  server = GRPC::RpcServer.new
+  port = server.add_http2_port "127.0.0.1:0", :this_port_is_insecure
+  server.handle SpannerMockServer.new
+  File.write(ENV["MOCK_PORT_FILE"], port.to_s) if ENV["MOCK_PORT_FILE"]
+
+  # 2. Print ONLY the port number to stdout for the parent to read
+  puts port
+  server.run_till_terminated
+rescue SignalException
+  exit(0)
+rescue StandardError => e
+  warn "Mock server crashed: #{e.message}"
+  warn e.backtrace.join("\n")
+  exit(1)
+end

spannerlib/wrappers/spannerlib-ruby/spec/spannerlib_ruby_spec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# rubocop:disable Style/GlobalVars
 # rubocop:disable RSpec/NoExpectationExample
 
 # Copyright 2025 Google LLC
@@ -17,57 +18,87 @@
 # limitations under the License.
 
 require "minitest/autorun"
-
-require "grpc"
-require "google/rpc/error_details_pb"
-require "google/spanner/v1/spanner_pb"
-require "google/spanner/v1/spanner_services_pb"
 require "google/cloud/spanner/v1/spanner"
-
-require_relative "mock_server/statement_result"
-require_relative "mock_server/spanner_mock_server"
+require "timeout"
+require "tmpdir" # Needed for the file-based handshake
 
 require_relative "../lib/spannerlib/ffi"
 require_relative "../lib/spannerlib/connection"
-require_relative "../lib/spannerlib/rows"
-
-READ_PIPE, WRITE_PIPE = IO.pipe
-GRPC.prefork
-
-SERVER_PID = fork do
-  GRPC.postfork_child
-  READ_PIPE.close
-  $stdout.sync = true
-  $stderr.sync = true
-
-  begin
-    server = GRPC::RpcServer.new
-    port = server.add_http2_port "localhost:0", :this_port_is_insecure
-    mock = SpannerMockServer.new
-    server.handle mock
-
-    WRITE_PIPE.puts port
-    WRITE_PIPE.close
-
-    server.run
-  rescue StandardError => e
-    warn "Mock server failed to start: #{e.message}"
-    exit(1)
+
+$server_pid = nil
+$server_port = nil
+$port_file = nil
+$any_failure = false
+
+Minitest.after_run do
+  if $server_pid
+    begin
+      Process.kill("TERM", $server_pid)
+      Process.wait($server_pid)
+    rescue Errno::ESRCH, Errno::ECHILD, Errno::EINVAL
+      # Process already dead
+    end
+  end
+  File.delete($port_file) if $port_file && File.exist?($port_file)
+  if $any_failure
+    puts "Tests Failed! Exiting with code 1"
+    $stdout.flush
+    Process.exit!(1)
+  else
+    puts "Tests Passed! Exiting with code 0"
+    $stdout.flush
+    Process.exit!(0)
   end
 end
 
-GRPC.postfork_parent
-WRITE_PIPE.close
+describe "Connection" do
+  def self.spawn_server
+    runner_path = File.expand_path(File.join(__dir__, "mock_server_runner.rb"))
 
-SERVER_PORT = READ_PIPE.gets.strip.to_i
-READ_PIPE.close
+    $port_file = File.join(Dir.tmpdir, "spanner_mock_port_#{Time.now.to_i}_#{rand(1000)}.txt")
 
-describe "Connection" do
-  before do
-    server_address = "localhost:#{SERVER_PORT}"
-    database_path = "projects/p/instances/i/databases/d"
+    # 2. Tell the runner where to write the port
+    env_vars = { "MOCK_PORT_FILE" => $port_file }
+
+    # 3. Spawn process inheriting stdout/stderr.
+    # This prevents the buffer deadlock.
+    Process.spawn(env_vars, RbConfig.ruby, "-Ilib", "-Ispec", runner_path, out: $stdout, err: $stderr)
+  end
+
+  def self.wait_for_port
+    start_time = Time.now
+    loop do
+      raise "Timed out waiting for mock server to write to #{$port_file}" if Time.now - start_time > 20
+
+      # 4. Poll the file for the port
+      if File.exist?($port_file)
+        content = File.read($port_file).strip
+        return content.to_i unless content.empty?
+      end
+
+      # Check if the server died
+      raise "Mock server exited unexpectedly!" if Process.waitpid($server_pid, Process::WNOHANG)
 
-    @dsn = "#{server_address}/#{database_path}?useplaintext=true"
+      sleep 0.1
+    end
+  end
+
+  def self.ensure_server_running!
+    return if $server_port
+
+    $server_pid = spawn_server
+
+    begin
+      $server_port = wait_for_port
+    rescue StandardError
+      Process.kill("TERM", $server_pid) if $server_pid
+      raise
+    end
+  end
+
+  before do
+    self.class.ensure_server_running!
+    @dsn = "127.0.0.1:#{$server_port}/projects/p/instances/i/databases/d?useplaintext=true"
 
     @pool_id = SpannerLib.create_pool(@dsn)
     @conn_id = SpannerLib.create_connection(@pool_id)
@@ -77,12 +108,11 @@
   after do
     @conn&.close
     SpannerLib.close_pool(@pool_id) if @pool_id
+    $any_failure = true unless failures.empty?
   end
 
   it "can execute SELECT 1" do
-    request_proto = Google::Cloud::Spanner::V1::ExecuteSqlRequest.new(
-      sql: "SELECT 1"
-    )
+    request_proto = Google::Cloud::Spanner::V1::ExecuteSqlRequest.new(sql: "SELECT 1")
     rows_object = @conn.execute(request_proto)
 
     decoded_rows = rows_object.map do |row_bytes|
@@ -108,13 +138,5 @@
     _(commit_resp.commit_timestamp).wont_be_nil
   end
 end
-
 # rubocop:enable RSpec/NoExpectationExample
-
-# --- 5. GLOBAL SHUTDOWN HOOK ---
-Minitest.after_run do
-  if SERVER_PID
-    Process.kill("KILL", SERVER_PID)
-    Process.wait(SERVER_PID)
-  end
-end
+# rubocop:enable Style/GlobalVars