spannerlib-ruby 0.1.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 287861a42225f8adaa1798a29d737b323817c19c005abbbbe0b2d11ee8f2a7f8
+  data.tar.gz: 1ff412d54ad8567f3422d621cae5078ddf9cff11cdd0da5abeb40c80990ae549
+SHA512:
+  metadata.gz: 2d7fab0308ec1aa0989febf32dcb3096215e2ebc356aeb944fed7a02aa334325c6c88fdbd2f55e939a5ae11f40952d1f3539a2bc06febac94b9efd649b6e784a
+  data.tar.gz: 8f131835872c9aacdaba9c7af151f98be51096eae2851369695b83f628b31c9d96af34fdc688fcc5f676f726b37f10d0f799bad5be75b09b2954b5345b5f94a5

data/.gitignore

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

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'lib/spanner_pb.rb'
+    - 'vendor/**/*'
+
+plugins:
+  - rubocop-rspec
+
+Layout/LineLength:
+  Max: 150
+
+Style/Documentation:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false
+
+# Add this block to disable the 'let' rule
+RSpec/InstanceVariable:
+  Enabled: false
+RSpec/BeforeAfterAll:
+  Enabled: false
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integration/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+
+group :development, :test do
+  gem "rake-compiler", "~> 1.0"
+  gem "rspec", "~> 3.0"
+  gem "rubocop", require: false
+  gem "rubocop-rspec", require: false
+end

data/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__)

data/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

data/lib/spannerlib/connection.rb

@@ -0,0 +1,91 @@
+# 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.
+
+# frozen_string_literal: true
+
+require_relative "ffi"
+require_relative "rows"
+
+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, proto_klass: Google::Cloud::Spanner::V1::CommitResponse)
+  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.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, proto_klass: Google::Cloud::Spanner::V1::CommitResponse)
+  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 = if request.respond_to?(:to_proto)
+              request.to_proto
+            else
+              request.is_a?(String) ? request : request.to_s
+            end
+    rows_id = SpannerLib.execute(@pool_id, @conn_id, bytes)
+    SpannerLib::Rows.new(self, rows_id)
+  end
+
+  # Execute batch DML/DDL request. Returns ExecuteBatchDmlResponse bytes (or nil).
+  def execute_batch(request)
+    bytes = if request.respond_to?(:to_proto)
+              request.to_proto
+            else
+              request.is_a?(String) ? request : request.to_s
+            end
+
+    SpannerLib.execute_batch(@pool_id, @conn_id, bytes, proto_klass: Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse)
+  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

data/lib/spannerlib/exceptions.rb

@@ -0,0 +1,24 @@
+# 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.
+
+# frozen_string_literal: true
+
+class SpannerLibException < StandardError
+  attr_reader :status
+
+  def initialize(msg = nil, status = nil)
+    super(msg)
+    @status = status
+  end
+end

data/lib/spannerlib/ffi.rb

@@ -0,0 +1,290 @@
+# 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.
+
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ModuleLength
+
+require "rubygems"
+require "bundler/setup"
+
+require "google/protobuf"
+require "google/rpc/status_pb"
+
+require "ffi"
+require_relative "message_handler"
+
+module SpannerLib
+  extend FFI::Library
+
+  ENV_OVERRIDE = ENV.fetch("SPANNERLIB_PATH", nil)
+
+  def self.platform_dir_from_host
+    host_os  = RbConfig::CONFIG["host_os"]
+    host_cpu = RbConfig::CONFIG["host_cpu"]
+
+    case host_os
+    when /darwin/
+      host_cpu =~ /arm|aarch64/ ? "aarch64-darwin" : "x86_64-darwin"
+    when /linux/
+      host_cpu =~ /arm|aarch64/ ? "aarch64-linux" : "x86_64-linux"
+    when /mswin|mingw|cygwin/
+      "x64-mingw32"
+    end
+  end
+
+  # 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
+  def self.library_path
+    if ENV_OVERRIDE && !ENV_OVERRIDE.empty?
+      return ENV_OVERRIDE if File.file?(ENV_OVERRIDE)
+
+      warn "SPANNERLIB_PATH set to #{ENV_OVERRIDE} but file not found"
+    end
+
+    lib_dir = File.expand_path(__dir__)
+    ext = FFI::Platform::LIBSUFFIX
+
+    platform = platform_dir_from_host
+    if platform
+      candidate = File.join(lib_dir, platform, "spannerlib.#{ext}")
+      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.
+    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
+  end
+  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+  ffi_lib library_path
+
+  class GoString < FFI::Struct
+    layout :p,   :pointer,
+           :len, :long
+  end
+
+  # GoBytes is the Ruby representation of a Go byte slice
+  class GoBytes < FFI::Struct
+    layout :p,   :pointer,
+           :len, :long,
+           :cap, :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,
+           :length,   :int,
+           :pointer,  :pointer
+  end
+
+  # --- Native Function Signatures ---
+  attach_function :CreatePool, [GoString.by_value], Message.by_value
+  attach_function :ClosePool, [:int64], Message.by_value
+  attach_function :CreateConnection, [:int64], Message.by_value
+  attach_function :CloseConnection, %i[int64 int64], Message.by_value
+  attach_function :WriteMutations, [:int64, :int64, GoBytes.by_value], Message.by_value
+  attach_function :BeginTransaction, [:int64, :int64, GoBytes.by_value], Message.by_value
+  attach_function :Commit, %i[int64 int64], Message.by_value
+  attach_function :Rollback, %i[int64 int64], Message.by_value
+  attach_function :Execute, [:int64, :int64, GoBytes.by_value], Message.by_value
+  attach_function :ExecuteBatch, [:int64, :int64, GoBytes.by_value], Message.by_value
+  attach_function :Metadata, %i[int64 int64 int64], Message.by_value
+  attach_function :Next, %i[int64 int64 int64 int32 int32], Message.by_value
+  attach_function :ResultSetStats, %i[int64 int64 int64], Message.by_value
+  attach_function :CloseRows, %i[int64 int64 int64], Message.by_value
+  attach_function :Release, [:int64], :void
+
+  # --- Ruby-friendly Wrappers ---
+
+  def self.create_pool(dsn)
+    dsn_str = dsn.to_s.dup
+    dsn_ptr = FFI::MemoryPointer.from_string(dsn_str)
+
+    go_dsn = GoString.new
+    go_dsn[:p] = dsn_ptr
+    go_dsn[:len] = dsn_str.bytesize
+
+    message = CreatePool(go_dsn)
+    handle_object_id_response(message, "CreatePool")
+  end
+
+  def self.close_pool(pool_id)
+    message = ClosePool(pool_id)
+    handle_status_response(message, "ClosePool")
+  end
+
+  def self.create_connection(pool_id)
+    message = CreateConnection(pool_id)
+    handle_object_id_response(message, "CreateConnection")
+  end
+
+  def self.close_connection(pool_id, conn_id)
+    message = CloseConnection(pool_id, conn_id)
+    handle_status_response(message, "CloseConnection")
+  end
+
+  def self.release(pinner)
+    Release(pinner)
+  end
+
+  def self.with_gobytes(bytes)
+    bytes ||= ""
+    len = bytes.bytesize
+    ptr = FFI::MemoryPointer.new(len)
+    ptr.write_bytes(bytes, 0, len) if len.positive?
+
+    go_bytes = GoBytes.new
+    go_bytes[:p] = ptr
+    go_bytes[:len] = len
+    go_bytes[:cap] = len
+
+    yield(go_bytes)
+  end
+
+  def self.ensure_release(message)
+    pinner = message[:pinner]
+    begin
+      yield
+    ensure
+      release(pinner) if pinner != 0
+    end
+  end
+
+  def self.handle_object_id_response(message, _func_name)
+    ensure_release(message) do
+      MessageHandler.new(message).object_id
+    end
+  end
+
+  def self.handle_status_response(message, _func_name)
+    ensure_release(message) do
+      MessageHandler.new(message).throw_if_error!
+    end
+    nil
+  end
+
+  def self.handle_data_response(message, _func_name, options = {})
+    proto_klass = options[:proto_klass]
+    ensure_release(message) do
+      MessageHandler.new(message).data(proto_klass: proto_klass)
+    end
+  end
+
+  # rubocop:disable Metrics/MethodLength
+  def self.read_error_message(message)
+    len = message[:length]
+    ptr = message[:pointer]
+    if len.positive? && !ptr.null?
+      raw_bytes = ptr.read_bytes(len)
+      begin
+        status_proto = ::Google::Rpc::Status.decode(raw_bytes)
+        "Status Proto { code: #{status_proto.code}, message: '#{status_proto.message}' }"
+      rescue StandardError => e
+        clean_string = raw_bytes.encode("UTF-8", invalid: :replace, undef: :replace, replace: "?").strip
+        "Failed to decode Status proto (code #{message[:code]}): #{e.class}: #{e.message} | Raw: #{clean_string}"
+      end
+    else
+      "No error message provided"
+    end
+  end
+  # rubocop:enable Metrics/MethodLength
+
+  def self.write_mutations(pool_id, conn_id, proto_bytes, options = {})
+    proto_klass = options[:proto_klass]
+    with_gobytes(proto_bytes) do |gobytes|
+      message = WriteMutations(pool_id, conn_id, gobytes)
+      handle_data_response(message, "WriteMutations", proto_klass: proto_klass)
+    end
+  end
+
+  def self.begin_transaction(pool_id, conn_id, proto_bytes)
+    with_gobytes(proto_bytes) do |gobytes|
+      message = BeginTransaction(pool_id, conn_id, gobytes)
+      handle_data_response(message, "BeginTransaction")
+    end
+  end
+
+  def self.commit(pool_id, conn_id, options = {})
+    proto_klass = options[:proto_klass]
+    message = Commit(pool_id, conn_id)
+    handle_data_response(message, "Commit", proto_klass: proto_klass)
+  end
+
+  def self.rollback(pool_id, conn_id)
+    message = Rollback(pool_id, conn_id)
+    handle_status_response(message, "Rollback")
+  end
+
+  def self.execute(pool_id, conn_id, proto_bytes)
+    with_gobytes(proto_bytes) do |gobytes|
+      message = Execute(pool_id, conn_id, gobytes)
+      handle_object_id_response(message, "Execute")
+    end
+  end
+
+  def self.execute_batch(pool_id, conn_id, proto_bytes, options = {})
+    proto_klass = options[:proto_klass]
+    with_gobytes(proto_bytes) do |gobytes|
+      message = ExecuteBatch(pool_id, conn_id, gobytes)
+      handle_data_response(message, "ExecuteBatch", proto_klass: proto_klass)
+    end
+  end
+
+  def self.metadata(pool_id, conn_id, rows_id)
+    message = Metadata(pool_id, conn_id, rows_id)
+    handle_data_response(message, "Metadata")
+  end
+
+  def self.next(pool_id, conn_id, rows_id, max_rows, fetch_size)
+    message = Next(pool_id, conn_id, rows_id, max_rows, fetch_size)
+    handle_data_response(message, "Next")
+  end
+
+  def self.result_set_stats(pool_id, conn_id, rows_id)
+    message = ResultSetStats(pool_id, conn_id, rows_id)
+    handle_data_response(message, "ResultSetStats")
+  end
+
+  def self.close_rows(pool_id, conn_id, rows_id)
+    message = CloseRows(pool_id, conn_id, rows_id)
+    handle_status_response(message, "CloseRows")
+  end
+end
+
+# rubocop:enable Metrics/ModuleLength

data/lib/spannerlib/message_handler.rb

@@ -0,0 +1,56 @@
+# 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.
+
+# frozen_string_literal: true
+
+# lib/spannerlib/message_handler.rb
+
+require "spannerlib/exceptions"
+
+module SpannerLib
+  class MessageHandler
+    def initialize(message)
+      @message = message
+    end
+
+    def object_id
+      throw_if_error!
+      @message[:objectId]
+    end
+
+    # Returns the data payload from the message.
+    # If a proto_klass is provided, it decodes the bytes into a Protobuf object.
+    # Otherwise, it returns the raw bytes as a string.
+    def data(proto_klass: nil)
+      throw_if_error!
+
+      len = @message[:length]
+      ptr = @message[:pointer]
+
+      return (proto_klass ? proto_klass.new : "") unless len.positive? && !ptr.null?
+
+      bytes = ptr.read_string(len)
+
+      proto_klass ? proto_klass.decode(bytes) : bytes
+    end
+
+    def throw_if_error!
+      code = @message[:code]
+      return if code.zero?
+
+      error_msg = SpannerLib.read_error_message(@message)
+      raise SpannerLibException, "Call failed with code #{code}: #{error_msg}"
+    end
+  end
+end

data/lib/spannerlib/pool.rb

@@ -0,0 +1,63 @@
+# 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.
+
+# frozen_string_literal: true
+
+require_relative "ffi"
+require_relative "connection"
+
+class Pool
+  attr_reader :id
+
+  def initialize(id)
+    @id = id
+    @closed = false
+  end
+
+  # Create a new Pool given a DSN string. Raises SpannerLibException on failure.
+  def self.create_pool(dsn)
+    begin
+      pool_id = SpannerLib.create_pool(dsn)
+    rescue StandardError => e
+      raise SpannerLibException, e.message
+    end
+
+    raise SpannerLibException, "failed to create pool" if pool_id.nil? || pool_id <= 0
+
+    Pool.new(pool_id)
+  end
+
+  # Close this pool and free native resources.
+  def close
+    return if @closed
+
+    SpannerLib.close_pool(@id)
+    @closed = true
+  end
+
+  # Create a new Connection associated with this Pool.
+  def create_connection
+    raise SpannerLibException, "pool closed" if @closed
+
+    begin
+      conn_id = SpannerLib.create_connection(@id)
+    rescue StandardError => e
+      raise SpannerLibException, e.message
+    end
+
+    raise SpannerLibException, "failed to create connection" if conn_id.nil? || conn_id <= 0
+
+    Connection.new(@id, conn_id)
+  end
+end