cloud_sql_ruby_connector 1.0.0

data/lib/cloud_sql_ruby_connector/credentials/metadata.rb

@@ -0,0 +1,50 @@
+# 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"
+
+module CloudSQLRubyConnector
+  module Credentials
+    # GCE/Cloud Run metadata server credentials
+    class Metadata < Base
+      METADATA_BASE = "http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default"
+
+      protected
+
+      def refresh_token(scope)
+        uri = URI("#{METADATA_BASE}/token?scopes=#{SCOPES[scope]}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.open_timeout = 2
+        http.read_timeout = 2
+
+        request = Net::HTTP::Get.new(uri)
+        request["Metadata-Flavor"] = "Google"
+
+        response = http.request(request)
+        data = JSON.parse(response.body)
+
+        raise AuthenticationError, "Failed to get metadata token: #{response.body}" unless response.code.to_i == 200
+
+        store_token(scope, data["access_token"], data["expires_in"])
+      rescue Errno::EHOSTUNREACH, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout
+        raise AuthenticationError, "Not running on GCE/Cloud Run and no credentials found"
+      rescue JSON::ParserError => e
+        raise AuthenticationError, "Invalid metadata response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/credentials/service_account.rb

@@ -0,0 +1,115 @@
+# 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 "openssl"
+require "net/http"
+require "json"
+require "base64"
+
+module CloudSQLRubyConnector
+  module Credentials
+    # Service Account credentials from JSON key file
+    class ServiceAccount < Base
+      attr_reader :client_email
+
+      # Load credentials from a JSON file
+      # @param path [String] path to the JSON key file
+      # @return [ServiceAccount, UserCredentials] depending on the credential type
+      def self.from_file(path)
+        data = JSON.parse(File.read(path))
+
+        if data["type"] == "authorized_user"
+          UserCredentials.new(data)
+        else
+          new(data)
+        end
+      end
+
+      def initialize(data)
+        super()
+        validate_required_fields!(data)
+        @client_email = data["client_email"]
+        @private_key = OpenSSL::PKey::RSA.new(data["private_key"])
+      end
+
+      private
+
+      def validate_required_fields!(data)
+        raise ConfigurationError, "Missing 'client_email' in service account credentials" if data["client_email"].nil?
+        raise ConfigurationError, "Missing 'private_key' in service account credentials" if data["private_key"].nil?
+      end
+
+      protected
+
+      def refresh_token(scope)
+        now = Time.now.to_i
+        payload = {
+          iss: @client_email,
+          scope: SCOPES[scope],
+          aud: TOKEN_URI,
+          iat: now,
+          exp: now + 3600
+        }
+
+        jwt = encode_jwt(payload)
+
+        uri = URI(TOKEN_URI)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/x-www-form-urlencoded"
+        request.body = URI.encode_www_form(
+          grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+          assertion: jwt
+        )
+
+        response = http.request(request)
+        data = JSON.parse(response.body)
+
+        unless response.code.to_i == 200
+          raise AuthenticationError, "Failed to get access token: #{data["error_description"] || data["error"]}"
+        end
+
+        store_token(scope, data["access_token"], data["expires_in"])
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise AuthenticationError, "Token request timed out: #{e.message}"
+      rescue JSON::ParserError => e
+        raise AuthenticationError, "Invalid token response: #{e.message}"
+      end
+
+      private
+
+      def encode_jwt(payload)
+        header = { alg: "RS256", typ: "JWT" }
+        segments = [
+          base64url_encode(header.to_json),
+          base64url_encode(payload.to_json)
+        ]
+        signing_input = segments.join(".")
+        signature = @private_key.sign("SHA256", signing_input)
+        segments << base64url_encode(signature)
+        segments.join(".")
+      end
+
+      def base64url_encode(data)
+        Base64.urlsafe_encode64(data, padding: false)
+      end
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/credentials/user_credentials.rb

@@ -0,0 +1,73 @@
+# 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"
+
+module CloudSQLRubyConnector
+  module Credentials
+    # User credentials from gcloud auth application-default login
+    class UserCredentials < Base
+      def initialize(data)
+        super()
+        validate_required_fields!(data)
+        @client_id = data["client_id"]
+        @client_secret = data["client_secret"]
+        @refresh_token_value = data["refresh_token"]
+      end
+
+      private
+
+      def validate_required_fields!(data)
+        raise ConfigurationError, "Missing 'client_id' in user credentials" if data["client_id"].nil?
+        raise ConfigurationError, "Missing 'client_secret' in user credentials" if data["client_secret"].nil?
+        raise ConfigurationError, "Missing 'refresh_token' in user credentials" if data["refresh_token"].nil?
+      end
+
+      protected
+
+      def refresh_token(scope)
+        uri = URI(TOKEN_URI)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/x-www-form-urlencoded"
+        request.body = URI.encode_www_form(
+          client_id: @client_id,
+          client_secret: @client_secret,
+          refresh_token: @refresh_token_value,
+          grant_type: "refresh_token"
+        )
+
+        response = http.request(request)
+        data = JSON.parse(response.body)
+
+        unless response.code.to_i == 200
+          raise AuthenticationError, "Failed to refresh token: #{data["error_description"] || data["error"]}"
+        end
+
+        store_token(scope, data["access_token"], data["expires_in"])
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise AuthenticationError, "Token refresh timed out: #{e.message}"
+      rescue JSON::ParserError => e
+        raise AuthenticationError, "Invalid token response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/errors.rb

@@ -0,0 +1,55 @@
+# 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
+  # Base error class for all Cloud SQL Connector errors
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code: nil)
+      @code = code
+      super(message)
+    end
+  end
+
+  # Raised when authentication fails
+  class AuthenticationError < Error
+    def initialize(message, code: "EAUTH")
+      super
+    end
+  end
+
+  # Raised when connection to Cloud SQL instance fails
+  class ConnectionError < Error
+    def initialize(message, code: "ECONNECTION")
+      super
+    end
+  end
+
+  # Raised when configuration is invalid
+  class ConfigurationError < Error
+    def initialize(message, code: "ECONFIG")
+      super
+    end
+  end
+
+  # Raised when IP address is not available
+  class IpAddressError < Error
+    def initialize(message, code: "ENOIPADDRESS")
+      super
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/ip_address_types.rb

@@ -0,0 +1,51 @@
+# 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
+  # IP address types for Cloud SQL connections
+  module IpAddressTypes
+    PUBLIC = "PUBLIC"
+    PRIVATE = "PRIVATE"
+    PSC = "PSC"
+
+    ALL = [PUBLIC, PRIVATE, PSC].freeze
+
+    class << self
+      def valid?(type)
+        ALL.include?(type.to_s.upcase)
+      end
+
+      def normalize(type)
+        normalized = type.to_s.upcase
+        unless valid?(normalized)
+          raise ConfigurationError,
+                "Invalid IP address type: #{type}. Valid types: #{ALL.join(", ")}"
+        end
+
+        normalized
+      end
+
+      # Returns the API key used in Cloud SQL Admin API response
+      def api_key(type)
+        case normalize(type)
+        when PUBLIC then "PRIMARY"
+        when PRIVATE then "PRIVATE"
+        when PSC then "PSC"
+        end
+      end
+    end
+  end
+end

data/lib/cloud_sql_ruby_connector/postgresql/connector.rb

@@ -0,0 +1,255 @@
+# 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 "openssl"
+require "socket"
+
+module CloudSQLRubyConnector
+  module PostgreSQL
+    # PostgreSQL connector for Cloud SQL connections
+    #
+    # Provides secure, authenticated connections to Cloud SQL PostgreSQL instances
+    # using ephemeral certificates and optional IAM authentication.
+    #
+    # @example Basic usage
+    #   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()")
+    #   conn.close
+    #   connector.close
+    #
+    # @example Using IAM authentication
+    #   connector = CloudSQLRubyConnector::PostgreSQL::Connector.new(
+    #     "my-project:us-central1:my-instance",
+    #     auth_type: :iam
+    #   )
+    #   conn = connector.connect(user: "sa@project.iam", dbname: "mydb")
+    #
+    class Connector
+      CLOUD_SQL_PORT = 3307
+      CERT_REFRESH_BUFFER = 300 # Refresh certificate 5 minutes before expiration
+
+      attr_reader :project, :region, :instance_name, :ip_type, :auth_type
+
+      # Initialize a new connector
+      #
+      # @param instance_connection_name [String] Cloud SQL instance connection name (PROJECT:REGION:INSTANCE)
+      # @param credentials [Credentials::Base] Optional credentials object
+      # @param ip_type [String, Symbol] IP address type: :public, :private, or :psc (default: :public)
+      # @param auth_type [String, Symbol] Authentication type: :password or :iam (default: :password)
+      # @param api_endpoint [String] Optional custom API endpoint
+      def initialize(instance_connection_name, credentials: nil, ip_type: IpAddressTypes::PUBLIC,
+                     auth_type: AuthTypes::PASSWORD, api_endpoint: nil)
+        @project, @region, @instance_name = parse_connection_name(instance_connection_name)
+        @ip_type = IpAddressTypes.normalize(ip_type)
+        @auth_type = AuthTypes.normalize(auth_type)
+        @credentials = credentials || default_credentials
+        @api_endpoint = api_endpoint
+
+        # Generate RSA key pair once per connector instance
+        @private_key, @public_key = generate_keys
+
+        # Certificate cache with expiration tracking
+        @cached_info = nil
+        @cert_expiration = Time.at(0)
+        @lock = Mutex.new
+
+        # SQL Admin API fetcher
+        @fetcher = SQLAdminFetcher.new(credentials: @credentials, api_endpoint: @api_endpoint)
+
+        # Track active proxies for cleanup
+        @proxies = []
+      end
+
+      # Create a connected PG::Connection
+      #
+      # @param user [String] Database username
+      # @param password [String] Database password (optional for IAM auth)
+      # @param dbname [String] Database name
+      # @param extra_options [Hash] Additional options to pass to PG.connect
+      # @return [PG::Connection] Connected PostgreSQL connection
+      def connect(user:, dbname:, password: nil, **extra_options)
+        require "pg"
+
+        validate_connection_params!(user: user)
+        conn_info = ensure_valid_connection_info!
+
+        effective_user = @auth_type == AuthTypes::IAM ? format_iam_user(user) : user
+        effective_password = @auth_type == AuthTypes::IAM ? @credentials.access_token(scope: :login) : password
+
+        ssl_socket = create_ssl_connection(conn_info)
+        proxy = SslProxy.new(ssl_socket)
+        proxy.start
+        @lock.synchronize { @proxies << proxy }
+
+        begin
+          PG.connect(
+            host: "127.0.0.1",
+            port: proxy.port,
+            user: effective_user,
+            password: effective_password,
+            dbname: dbname,
+            sslmode: "disable",
+            **extra_options
+          )
+        rescue StandardError => e
+          proxy.stop
+          raise e
+        end
+      end
+
+      # Get connection options that can be used with PG.connect
+      # This is an alternative to using #connect directly
+      #
+      # @return [Hash] Connection options including :stream proc
+      def get_options
+        conn_info = ensure_valid_connection_info!
+
+        {
+          stream: -> { create_ssl_connection(conn_info) },
+          ip_address: conn_info[:ip_address],
+          server_ca_cert: conn_info[:server_ca_cert],
+          client_cert: conn_info[:client_cert],
+          private_key: conn_info[:private_key]
+        }
+      end
+
+      # Get the IP address for the instance
+      #
+      # @return [String] IP address
+      def ip_address
+        ensure_valid_connection_info![:ip_address]
+      end
+
+      # Close the connector and clean up resources
+      def close
+        @lock.synchronize do
+          @proxies.each(&:stop)
+          @proxies.clear
+          @cached_info = nil
+        end
+      end
+
+      private
+
+      def parse_connection_name(name)
+        parts = name.to_s.split(":")
+        unless parts.length == 3
+          raise ConfigurationError,
+                "Invalid instance connection name '#{name}'. Expected format: PROJECT:REGION:INSTANCE"
+        end
+
+        parts
+      end
+
+      def generate_keys
+        key = OpenSSL::PKey::RSA.new(2048)
+        [key.to_pem, key.public_key.to_pem]
+      end
+
+      def default_credentials
+        if ENV["GOOGLE_APPLICATION_CREDENTIALS"]
+          return Credentials::ServiceAccount.from_file(ENV["GOOGLE_APPLICATION_CREDENTIALS"])
+        end
+
+        gcloud_path = File.expand_path("~/.config/gcloud/application_default_credentials.json")
+        return Credentials::ServiceAccount.from_file(gcloud_path) if File.exist?(gcloud_path)
+
+        Credentials::Metadata.new
+      rescue JSON::ParserError => e
+        raise ConfigurationError, "Invalid credentials file: #{e.message}"
+      end
+
+      def ensure_valid_connection_info!
+        @lock.synchronize do
+          refresh_connection_info! if @cached_info.nil? || Time.now > (@cert_expiration - CERT_REFRESH_BUFFER)
+          @cached_info
+        end
+      end
+
+      def refresh_connection_info!
+        metadata = @fetcher.fetch_metadata(
+          project: @project,
+          region: @region,
+          instance: @instance_name
+        )
+
+        cert_data = @fetcher.fetch_ephemeral_cert(
+          project: @project,
+          instance: @instance_name,
+          public_key: @public_key,
+          auth_type: @auth_type
+        )
+
+        ip_address = select_ip_address(metadata[:ip_addresses])
+
+        @cert_expiration = cert_data[:expiration]
+        @cached_info = {
+          ip_address: ip_address,
+          server_ca_cert: metadata[:server_ca_cert],
+          client_cert: cert_data[:cert],
+          private_key: @private_key
+        }
+      end
+
+      def select_ip_address(ip_addresses)
+        api_key = IpAddressTypes.api_key(@ip_type)
+        ip = ip_addresses[api_key]
+
+        unless ip
+          raise IpAddressError.new(
+            "Cannot connect to instance, #{@ip_type} IP address not found",
+            code: "ENO#{@ip_type}IPADDRESS"
+          )
+        end
+
+        ip
+      end
+
+      def validate_connection_params!(user:)
+        raise ConfigurationError, "User is required for database connection" if user.nil? || user.empty?
+      end
+
+      def format_iam_user(user)
+        suffix = ".gserviceaccount.com"
+        user.end_with?(suffix) ? user[0...-suffix.length] : user
+      end
+
+      def create_ssl_connection(conn_info)
+        ssl_context = OpenSSL::SSL::SSLContext.new
+        ssl_context.min_version = OpenSSL::SSL::TLS1_3_VERSION
+        ssl_context.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+        ssl_context.cert = OpenSSL::X509::Certificate.new(conn_info[:client_cert])
+        ssl_context.key = OpenSSL::PKey::RSA.new(conn_info[:private_key])
+
+        cert_store = OpenSSL::X509::Store.new
+        cert_store.add_cert(OpenSSL::X509::Certificate.new(conn_info[:server_ca_cert]))
+        ssl_context.cert_store = cert_store
+
+        tcp_socket = Socket.tcp(conn_info[:ip_address], CLOUD_SQL_PORT, connect_timeout: 30)
+
+        ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_socket, ssl_context)
+        ssl_socket.sync_close = true
+        ssl_socket.connect
+
+        ssl_socket
+      rescue Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::EHOSTUNREACH => e
+        raise ConnectionError, "Failed to connect to Cloud SQL instance: #{e.message}"
+      end
+    end
+  end
+end