cloud_sql_ruby_connector 1.0.0

data/lib/cloud_sql_ruby_connector/rails.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Martin Milo
+#
+# 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_relative "../cloud_sql_ruby_connector"
+require "active_record"
+require "active_record/connection_adapters/postgresql_adapter"
+
+module CloudSQLRubyConnector
+  # Rails integration for Cloud SQL Connector
+  #
+  # @example Usage in config/initializers/cloud_sql.rb
+  #   require "cloud_sql_ruby_connector/rails"
+  #
+  #   CloudSQLRubyConnector::Rails.setup!(
+  #     instance: "project:region:instance",
+  #     ip_type: :private,
+  #     auth_type: :iam
+  #   )
+  #
+  # @example Then in database.yml
+  #   production:
+  #     adapter: cloud_sql_postgresql
+  #     database: myapp_production
+  #     username: myuser@project.iam.gserviceaccount.com
+  #     pool: 5
+  #
+  module Rails
+    class << self
+      attr_reader :connector
+
+      # Set up the Cloud SQL connector for Rails
+      #
+      # @param instance [String] Cloud SQL instance connection name
+      # @param ip_type [String, Symbol] IP address type (default: :public)
+      # @param auth_type [String, Symbol] Authentication type (default: :password)
+      # @param credentials [Credentials::Base] Optional custom credentials
+      def setup!(instance:, ip_type: IpAddressTypes::PUBLIC, auth_type: AuthTypes::PASSWORD, credentials: nil)
+        @connector = PostgreSQL::Connector.new(
+          instance,
+          ip_type: ip_type,
+          auth_type: auth_type,
+          credentials: credentials
+        )
+        register_adapter!
+        register_shutdown_hook!
+      end
+
+      # Close the connector and clean up resources
+      def shutdown!
+        @connector&.close
+        @connector = nil
+      end
+
+      private
+
+      def register_adapter!
+        ActiveRecord::ConnectionAdapters.register(
+          "cloud_sql_postgresql",
+          "CloudSQLRubyConnector::Rails::CloudSQLPostgreSQLAdapter",
+          "cloud_sql_ruby_connector/rails"
+        )
+      end
+
+      def register_shutdown_hook!
+        at_exit { shutdown! }
+      end
+    end
+
+    # Custom adapter that uses CloudSQLRubyConnector for connections
+    class CloudSQLPostgreSQLAdapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+      ADAPTER_NAME = "CloudSQL PostgreSQL"
+
+      # PG connection options that can be passed through to PG.connect
+      # See: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
+      ALLOWED_PG_OPTIONS = %i[
+        application_name
+        client_encoding
+        connect_timeout
+        options
+        keepalives
+        keepalives_idle
+        keepalives_interval
+        keepalives_count
+        tcp_user_timeout
+        target_session_attrs
+      ].freeze
+
+      class << self
+        # In Rails 7.1+, new_client receives processed conn_params (user, dbname)
+        # not the raw config (username, database)
+        def new_client(conn_params)
+          connector = CloudSQLRubyConnector::Rails.connector
+          raise ConfigurationError, "CloudSQLRubyConnector::Rails.setup! not called" unless connector
+
+          # conn_params already has :user and :dbname (processed by parent's initialize)
+          cfg = if conn_params.respond_to?(:symbolize_keys)
+                  conn_params.symbolize_keys
+                else
+                  conn_params.to_h.transform_keys(&:to_sym)
+                end
+
+          # Only pass through known PG connection options
+          extra_options = cfg.slice(*ALLOWED_PG_OPTIONS)
+
+          connector.connect(
+            user: cfg[:user],
+            password: cfg[:password],
+            dbname: cfg[:dbname],
+            **extra_options
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/sqladmin_fetcher.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Martin Milo
+#
+# 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 "net/http"
+require "json"
+require "openssl"
+
+module CloudSQLRubyConnector
+  # Fetches instance metadata and ephemeral certificates from Cloud SQL Admin API
+  class SQLAdminFetcher
+    API_VERSION = "v1beta4"
+    DEFAULT_ENDPOINT = "https://sqladmin.googleapis.com"
+    HTTP_TIMEOUT = 30 # seconds
+
+    def initialize(credentials:, api_endpoint: nil)
+      @credentials = credentials
+      @api_endpoint = api_endpoint || DEFAULT_ENDPOINT
+    end
+
+    # Fetch instance metadata including IP addresses and server CA certificate
+    # @param project [String] Google Cloud project ID
+    # @param region [String] Cloud SQL instance region
+    # @param instance [String] Cloud SQL instance name
+    # @return [Hash] instance metadata
+    def fetch_metadata(project:, region:, instance:)
+      token = @credentials.access_token(scope: :admin)
+      uri = URI("#{@api_endpoint}/sql/#{API_VERSION}/projects/#{project}/instances/#{instance}/connectSettings")
+
+      response = http_get(uri, token)
+      data = parse_response(response)
+
+      raise ConfigurationError, "Region mismatch: expected #{region}, got #{data["region"]}" if data["region"] != region
+
+      ip_addresses = parse_ip_addresses(
+        data["ipAddresses"],
+        data["dnsName"],
+        data["dnsNames"],
+        data["pscEnabled"]
+      )
+
+      server_ca_cert = data.dig("serverCaCert", "cert")
+      raise ConnectionError, "No valid CA certificate found for instance" if server_ca_cert.nil?
+
+      {
+        ip_addresses: ip_addresses,
+        server_ca_cert: server_ca_cert,
+        database_version: data["databaseVersion"],
+        dns_name: data["dnsName"]
+      }
+    end
+
+    # Fetch an ephemeral certificate for client authentication
+    # @param project [String] Google Cloud project ID
+    # @param instance [String] Cloud SQL instance name
+    # @param public_key [String] RSA public key in PEM format
+    # @param auth_type [String] Authentication type (PASSWORD or IAM)
+    # @return [Hash] certificate data with :cert and :expiration
+    def fetch_ephemeral_cert(project:, instance:, public_key:, auth_type:)
+      token = @credentials.access_token(scope: :admin)
+      uri = URI("#{@api_endpoint}/sql/#{API_VERSION}/projects/#{project}/instances/#{instance}:generateEphemeralCert")
+
+      body = { "public_key" => public_key }
+
+      # For IAM auth, include the login token
+      if auth_type == AuthTypes::IAM
+        login_token = @credentials.access_token(scope: :login)
+        body["access_token"] = login_token
+      end
+
+      response = http_post(uri, token, body)
+      data = parse_response(response)
+
+      cert_pem = data.dig("ephemeralCert", "cert")
+      raise ConnectionError, "Failed to retrieve ephemeral certificate" if cert_pem.nil?
+
+      cert = OpenSSL::X509::Certificate.new(cert_pem)
+
+      {
+        cert: cert_pem,
+        expiration: cert.not_after
+      }
+    end
+
+    private
+
+    def parse_response(response)
+      data = JSON.parse(response.body)
+
+      if response.code.to_i >= 400
+        error_msg = data.dig("error", "message") || response.body
+        raise ConnectionError, "API request failed: #{error_msg}"
+      end
+
+      data
+    rescue JSON::ParserError => e
+      raise ConnectionError, "Invalid API response: #{e.message}"
+    end
+
+    # Parse IP addresses from API response
+    # Node.js ref: https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector/blob/main/src/sqladmin-fetcher.ts
+    def parse_ip_addresses(ip_data, dns_name, dns_names, psc_enabled)
+      ip_addresses = {}
+
+      # Parse regular IP addresses (PUBLIC/PRIVATE)
+      ip_data&.each do |ip|
+        case ip["type"]
+        when "PRIMARY"
+          ip_addresses["PRIMARY"] = ip["ipAddress"]
+        when "PRIVATE"
+          ip_addresses["PRIVATE"] = ip["ipAddress"]
+        end
+      end
+
+      # PSC uses DNS names, not IP addresses
+      # First, check dns_names array for PSC connection type
+      if dns_names.is_a?(Array)
+        dns_names.each do |dnm|
+          if dnm["connectionType"] == "PRIVATE_SERVICE_CONNECT" && dnm["dnsScope"] == "INSTANCE"
+            ip_addresses["PSC"] = dnm["name"]
+            break
+          end
+        end
+      end
+
+      # Fallback to legacy dns_name field if PSC not found and pscEnabled is true
+      ip_addresses["PSC"] = dns_name if ip_addresses["PSC"].nil? && dns_name && psc_enabled
+
+      ip_addresses
+    end
+
+    def http_get(uri, token)
+      http = create_http_client(uri)
+
+      request = Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{token}"
+      request["Content-Type"] = "application/json"
+
+      http.request(request)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise ConnectionError, "Request timed out: #{e.message}"
+    rescue StandardError => e
+      raise ConnectionError, "HTTP request failed: #{e.message}"
+    end
+
+    def http_post(uri, token, body)
+      http = create_http_client(uri)
+
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{token}"
+      request["Content-Type"] = "application/json"
+      request.body = body.to_json
+
+      http.request(request)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise ConnectionError, "Request timed out: #{e.message}"
+    rescue StandardError => e
+      raise ConnectionError, "HTTP request failed: #{e.message}"
+    end
+
+    def create_http_client(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.open_timeout = HTTP_TIMEOUT
+      http.read_timeout = HTTP_TIMEOUT
+      http
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/ssl_proxy.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Martin Milo
+#
+# 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 "socket"
+
+module CloudSQLRubyConnector
+  # Local TCP proxy that bridges pg (plain) to Cloud SQL (SSL)
+  #
+  # This proxy is necessary because Cloud SQL requires direct TLS connections,
+  # but libpq (PostgreSQL client) sends an SSLRequest message first, which
+  # Cloud SQL doesn't understand. The proxy accepts plain TCP connections
+  # locally and forwards them over the pre-established SSL connection.
+  class SslProxy
+    attr_reader :port
+
+    def initialize(ssl_socket)
+      @ssl_socket = ssl_socket
+      @server = TCPServer.new("127.0.0.1", 0) # Port 0 = kernel assigns available port
+      @port = @server.addr[1]
+      @running = false
+      @threads = []
+      @mutex = Mutex.new
+    end
+
+    # Start the proxy server in a background thread
+    def start
+      @running = true
+      @accept_thread = Thread.new { accept_loop }
+    end
+
+    # Stop the proxy server and clean up resources
+    def stop
+      @mutex.synchronize do
+        @running = false
+        @accept_thread&.kill if @accept_thread&.alive?
+        @threads.each { |t| t.kill if t.alive? }
+        @threads.clear
+        begin
+          @server.close
+        rescue StandardError
+          nil
+        end
+        begin
+          @ssl_socket.close
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    private
+
+    def accept_loop
+      client = @server.accept
+      @server.close # Close listener immediately - we only need one client
+
+      @mutex.synchronize do
+        @threads << Thread.new { forward(client, @ssl_socket) }
+        @threads << Thread.new { forward(@ssl_socket, client) }
+      end
+    rescue IOError
+      # Server closed
+    end
+
+    def forward(from, to)
+      while @running
+        data = from.readpartial(16_384)
+        to.write(data)
+      end
+    rescue EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE
+      # Close the other side to unblock the paired thread
+      begin
+        to.close
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Martin Milo
+#
+# 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.
+
+module CloudSQLRubyConnector
+  VERSION = "1.0.0"
+end

data/lib/cloud_sql_ruby_connector.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Martin Milo
+#
+# 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_relative "cloud_sql_ruby_connector/version"
+require_relative "cloud_sql_ruby_connector/errors"
+require_relative "cloud_sql_ruby_connector/ip_address_types"
+require_relative "cloud_sql_ruby_connector/auth_types"
+require_relative "cloud_sql_ruby_connector/credentials/base"
+require_relative "cloud_sql_ruby_connector/credentials/service_account"
+require_relative "cloud_sql_ruby_connector/credentials/user_credentials"
+require_relative "cloud_sql_ruby_connector/credentials/metadata"
+require_relative "cloud_sql_ruby_connector/ssl_proxy"
+require_relative "cloud_sql_ruby_connector/sqladmin_fetcher"
+require_relative "cloud_sql_ruby_connector/postgresql/connector"
+
+# Cloud SQL Ruby Connector
+#
+# A Ruby connector for Google Cloud SQL that provides secure, IAM-based
+# authentication without requiring the Cloud SQL Auth Proxy.
+#
+# @example Basic usage with PostgreSQL
+#   require 'cloud_sql_ruby_connector'
+#   require 'pg'
+#
+#   connector = CloudSQLRubyConnector::PostgreSQL::Connector.new("my-project:us-central1:my-instance")
+#   conn = connector.connect(user: "myuser", password: "mypass", dbname: "mydb")
+#   result = conn.exec("SELECT NOW()")
+#   puts result.first
+#   conn.close
+#   connector.close
+#
+# @example Using IAM authentication
+#   connector = CloudSQLRubyConnector::PostgreSQL::Connector.new(
+#     "my-project:us-central1:my-instance",
+#     auth_type: :iam,
+#     ip_type: :private
+#   )
+#   conn = connector.connect(
+#     user: "service-account@project.iam.gserviceaccount.com",
+#     dbname: "mydb"
+#   )
+#
+module CloudSQLRubyConnector
+  module PostgreSQL
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: cloud_sql_ruby_connector
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Martin Milo
+bindir: exe
+cert_chain: []
+date: 2026-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: An unofficial Ruby connector for Google Cloud SQL that provides secure,
+  IAM-based authentication without requiring the Cloud SQL Auth Proxy.
+email:
+- milomartin.za@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- SECURITY.md
+- lib/cloud_sql_ruby_connector.rb
+- lib/cloud_sql_ruby_connector/auth_types.rb
+- lib/cloud_sql_ruby_connector/credentials/base.rb
+- lib/cloud_sql_ruby_connector/credentials/metadata.rb
+- lib/cloud_sql_ruby_connector/credentials/service_account.rb
+- lib/cloud_sql_ruby_connector/credentials/user_credentials.rb
+- lib/cloud_sql_ruby_connector/errors.rb
+- lib/cloud_sql_ruby_connector/ip_address_types.rb
+- lib/cloud_sql_ruby_connector/postgresql/connector.rb
+- lib/cloud_sql_ruby_connector/rails.rb
+- lib/cloud_sql_ruby_connector/sqladmin_fetcher.rb
+- lib/cloud_sql_ruby_connector/ssl_proxy.rb
+- lib/cloud_sql_ruby_connector/version.rb
+homepage: https://github.com/martinmilo/cloud-sql-ruby-connector
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/martinmilo/cloud-sql-ruby-connector
+  source_code_uri: https://github.com/martinmilo/cloud-sql-ruby-connector
+  changelog_uri: https://github.com/martinmilo/cloud-sql-ruby-connector/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Cloud SQL Ruby Connector
+test_files: []