feat(ruby): Add Ruby FFI wrapper for spannerlib

spannerlib/.gitignore

@@ -1,3 +1,8 @@
 spannerlib.h
 spannerlib.so
 grpc_server
+vendor/bundle
+shared/
+*.gem
+.DS_Store
+*.swp

spannerlib/wrappers/spannerlib-ruby/.github/workflows/main.yml

@@ -0,0 +1,27 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby:
+          - '3.3.1'
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run the default task
+        run: bundle exec rake

spannerlib/wrappers/spannerlib-ruby/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.rspec_status
+/vendor/bundle
+/shared/
+*.gem
+
+.DS_Store
+*.swp

spannerlib/wrappers/spannerlib-ruby/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

spannerlib/wrappers/spannerlib-ruby/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

spannerlib/wrappers/spannerlib-ruby/Gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in spannerlib-ruby.gemspec
+gemspec
+
+gem "irb"
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"
+
+gem 'ffi'
+gem 'google-protobuf', '~> 3.19'
+gem 'grpc', '~> 1.60'
+gem 'googleapis-common-protos', '~> 1.0'
+
+gem 'google-cloud-spanner'

spannerlib/wrappers/spannerlib-ruby/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

spannerlib/wrappers/spannerlib-ruby/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "spannerlib/ruby"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

spannerlib/wrappers/spannerlib-ruby/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

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

@@ -0,0 +1,82 @@
+require_relative 'ffi'
+
+class Connection
+  attr_reader :pool_id, :conn_id
+
+  def initialize(pool_id, conn_id)
+    @pool_id = pool_id
+    @conn_id = conn_id
+  end
+
+  # Accepts either an object that responds to `to_proto` or a raw string/bytes
+  # containing the serialized mutation proto. We avoid requiring the protobuf
+  # definitions at load time so specs that don't need them can run.
+  def write_mutations(mutation_group)
+    req_bytes = if mutation_group.respond_to?(:to_proto)
+                  mutation_group.to_proto
+                elsif mutation_group.is_a?(String)
+                  mutation_group
+                else
+                  mutation_group.to_s
+                end
+
+    SpannerLib.write_mutations(@pool_id, @conn_id, req_bytes)
+  end
+
+  # Begin a read/write transaction on this connection. Accepts TransactionOptions proto or bytes.
+  # Returns message bytes (or nil) — higher-level parsing not implemented here.
+  def begin_transaction(transaction_options = nil)
+    bytes = if transaction_options.respond_to?(:to_proto)
+              transaction_options.to_proto
+            else
+              transaction_options && transaction_options.is_a?(String) ? transaction_options : transaction_options&.to_s
+            end
+    SpannerLib.begin_transaction(@pool_id, @conn_id, bytes)
+  end
+
+  # Commit the current transaction. Returns CommitResponse bytes or nil.
+  def commit
+    SpannerLib.commit(@pool_id, @conn_id)
+  end
+
+  # Rollback the current transaction.
+  def rollback
+    SpannerLib.rollback(@pool_id, @conn_id)
+    nil
+  end
+
+  # Execute SQL request (expects a request object with to_proto or raw bytes). Returns message bytes (or nil).
+  def execute(request)
+    bytes = request.respond_to?(:to_proto) ? request.to_proto : request.is_a?(String) ? request : request.to_s
+    SpannerLib.execute(@pool_id, @conn_id, bytes)
+  end
+
+  # Execute batch DML/DDL request. Returns ExecuteBatchDmlResponse bytes (or nil).
+  def execute_batch(request)
+    bytes = request.respond_to?(:to_proto) ? request.to_proto : request.is_a?(String) ? request : request.to_s
+    SpannerLib.execute_batch(@pool_id, @conn_id, bytes)
+  end
+
+  # Rows helpers — return raw message bytes (caller should parse them).
+  def metadata(rows_id)
+    SpannerLib.metadata(@pool_id, @conn_id, rows_id)
+  end
+
+  def next_rows(rows_id, num_rows, encoding = 0)
+    SpannerLib.next(@pool_id, @conn_id, rows_id, num_rows, encoding)
+  end
+
+  def result_set_stats(rows_id)
+    SpannerLib.result_set_stats(@pool_id, @conn_id, rows_id)
+  end
+
+  def close_rows(rows_id)
+    SpannerLib.close_rows(@pool_id, @conn_id, rows_id)
+  end
+
+  # Closes this connection. Any active transaction on the connection is rolled back.
+  def close
+    SpannerLib.close_connection(@pool_id, @conn_id)
+    nil
+  end
+end

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

@@ -0,0 +1,8 @@
+class SpannerLibException < StandardError
+  attr_reader :status
+
+  def initialize(msg = nil, status = nil)
+    super(msg)
+    @status = status
+  end
+end