aws_advanced_ruby_driver_wrapper 1.0.0

data/lib/aws_advanced_ruby_driver_wrapper/errors/mysql_error_handler.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 'error_handler'
+
+module AwsAdvancedRubyDriverWrapper
+  module Errors
+    class MysqlErrorHandler
+      include ErrorHandler
+
+      ACCESS_ERROR_SQL_STATE = '28000'
+      READ_ONLY_ERROR_CODES = Set[1290, 1836].freeze
+      NETWORK_ERROR_CODES = Set[
+        2002, # CR_CONNECTION_ERROR (can't connect via socket)
+        2003, # CR_CONN_HOST_ERROR (can't connect to host)
+        2006, # CR_SERVER_GONE_ERROR (server has gone away)
+        2013, # CR_SERVER_LOST (lost connection during query)
+        2026, # CR_SSL_CONNECTION_ERROR
+        2055  # CR_SERVER_LOST_EXTENDED (lost connection with state info)
+      ].freeze
+
+      def initialize(driver_dialect)
+        @driver_dialect = driver_dialect
+      end
+
+      def network_error?(error)
+        return true if super
+
+        check_cause_chain(error) { |_, current| connection_error_network?(current) }
+      end
+
+      def network_error_by_sql_state?(sql_state)
+        return false if sql_state.nil?
+
+        sql_state.start_with?('08') && sql_state != '08004'
+      end
+
+      def login_error_by_sql_state?(sql_state)
+        return false if sql_state.nil?
+
+        sql_state == ACCESS_ERROR_SQL_STATE
+      end
+
+      def read_only_error?(error)
+        check_cause_chain(error) do |sql_state, ex|
+          error_code = ex.respond_to?(:error_number) ? ex.error_number : nil
+          read_only_error_by_sql_state?(sql_state, error_code)
+        end
+      end
+
+      def read_only_error_by_sql_state?(sql_state, error_code = nil)
+        sql_state == 'HY000' && !error_code.nil? && READ_ONLY_ERROR_CODES.include?(error_code)
+      end
+
+      private
+
+      def connection_error_network?(error)
+        return false unless defined?(Mysql2::Error::ConnectionError) && error.is_a?(Mysql2::Error::ConnectionError)
+
+        error_number = error.respond_to?(:error_number) ? error.error_number : nil
+        return true if error_number && NETWORK_ERROR_CODES.include?(error_number)
+
+        false
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/errors/pg_error_handler.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 'error_handler'
+
+module AwsAdvancedRubyDriverWrapper
+  module Errors
+    class PgErrorHandler
+      include ErrorHandler
+
+      NETWORK_SQL_STATE_PREFIXES = %w[57P01 57P02 57P03 58 08 99 F0].freeze
+      ACCESS_ERROR_SQL_STATES = Set['08004', '28P01', '28000'].freeze
+      READ_ONLY_SQL_STATE = '25006'
+      LOGIN_ERROR_MESSAGE = 'authentication failed'
+      NETWORK_ERROR_MESSAGES = [
+        'unexpected eof',
+        'closed the connection unexpectedly',
+        'reset by peer',
+        'could not receive data',
+        'could not send data',
+        'connection not open',
+        'no connection to the server',
+        'connection is closed',
+        'broken pipe',
+        'terminating connection due to administrator command',
+        "can't get socket descriptor",
+        'ssl connection has been closed unexpectedly'
+      ].freeze
+
+      # Failures raised while establishing a connection, where the server was never reached and so
+      # never had the chance to accept or reject the login. These are transient and worth retrying.
+      # libpq discards the structured error fields for connect-time failures, so the message text
+      # is the only signal available.
+      CONNECT_FAILURE_MESSAGES = [
+        'connection refused',
+        'timeout expired',
+        'could not translate host name',
+        'no route to host',
+        'network is unreachable',
+        'host is unreachable',
+        'could not connect to server',
+        'no such file or directory', # unix socket path does not exist
+        'connection timed out'
+      ].freeze
+
+      # Rejections issued by a server that was successfully reached. Retrying to connect is futile because
+      # the cause is the credentials, the requested database, or server configuration rather than the network path.
+      SERVER_REJECTION_MESSAGES = [
+        LOGIN_ERROR_MESSAGE,
+        'pg_hba.conf',
+        'does not exist',
+        'is not permitted',
+        'too many clients'
+      ].freeze
+
+      def initialize(driver_dialect)
+        @driver_dialect = driver_dialect
+      end
+
+      def network_error?(error)
+        return true if super
+
+        check_cause_chain(error) { |_, current| connection_bad_network_error?(current) }
+      end
+
+      def network_error_by_sql_state?(sql_state)
+        return false if sql_state.nil?
+
+        NETWORK_SQL_STATE_PREFIXES.any? { |prefix| sql_state.start_with?(prefix) }
+      end
+
+      def login_error?(error)
+        return true if super
+
+        # PG::ConnectionBad from auth failure during connect may not carry a SQLSTATE.
+        # Fall back to message inspection.
+        if defined?(PG::ConnectionBad) && error.is_a?(PG::ConnectionBad)
+          msg = error.message
+          return msg.include?(LOGIN_ERROR_MESSAGE) if msg
+        end
+
+        false
+      end
+
+      def login_error_by_sql_state?(sql_state)
+        return false if sql_state.nil?
+
+        ACCESS_ERROR_SQL_STATES.include?(sql_state)
+      end
+
+      def read_only_error_by_sql_state?(sql_state, _error_code = nil)
+        sql_state == READ_ONLY_SQL_STATE
+      end
+
+      private
+
+      def connection_bad_network_error?(error)
+        return false unless defined?(PG::ConnectionBad) && error.is_a?(PG::ConnectionBad)
+
+        msg = error.message&.downcase
+        return false if msg.nil?
+        return false if server_rejection?(msg)
+
+        NETWORK_ERROR_MESSAGES.any? { |pattern| msg.include?(pattern) } ||
+          CONNECT_FAILURE_MESSAGES.any? { |pattern| msg.include?(pattern) }
+      end
+
+      def server_rejection?(msg)
+        SERVER_REJECTION_MESSAGES.any? { |pattern| msg.include?(pattern) }
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/errors.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 AwsAdvancedRubyDriverWrapper
+  module Errors
+    class AwsError < StandardError
+      attr_reader :connection_broken, :needs_reconfiguration
+
+      def initialize(message, connection_broken: false, needs_reconfiguration: false)
+        super(message)
+        @needs_reconfiguration = needs_reconfiguration
+        @connection_broken = connection_broken
+      end
+    end
+
+    class FailoverFailedError < AwsError
+      def initialize(message)
+        super(message, connection_broken: true)
+      end
+    end
+
+    class FailoverSuccessError < AwsError
+      def initialize
+        super(
+          'The active SQL connection has changed due to a connection failure. Please re-configure session state if required.',
+          needs_reconfiguration: true)
+      end
+    end
+
+    class TransactionStateUnknownError < AwsError
+      def initialize
+        super(
+          'Transaction resolution unknown. Please re-configure session state if required and retry the transaction.',
+          connection_broken: true,
+          needs_reconfiguration: true
+        )
+      end
+    end
+
+    class IamAuthError < AwsError; end
+    class SecretsManagerAuthError < AwsError; end
+    class PluginConflictError < AwsError; end
+    class BlueGreenTimeoutError < AwsError; end
+    class BlueGreenSwitchoverError < AwsError; end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/host/connection_string_host_list_provider.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 '../errors'
+require_relative 'host_info'
+require_relative 'host_role'
+
+module AwsAdvancedRubyDriverWrapper
+  module Host
+    # A static host list provider that parses the connection string to determine host information.
+    # The host list is determined once during initialization and does not change over time.
+    class ConnectionStringHostListProvider
+      # @param service_container [Services::ServiceContainer]
+      def initialize(service_container:)
+        @service_container = service_container
+        @hosts = []
+        @initialized = false
+      end
+
+      # Returns the static host list parsed from the connection string.
+      # @return [Array<HostInfo>]
+      def refresh
+        initialize_hosts
+        @hosts.map(&:deep_dup)
+      end
+
+      # Same as {#refresh} — the host list is static and never changes.
+      # @param _verify_writer [Boolean] unused; accepted for compatibility with other host list providers.
+      # @param _timeout_ms [Integer] unused; accepted for compatibility with other host list providers.
+      # @return [Array<HostInfo>]
+      def force_refresh(_verify_writer = false, _timeout_ms = 0)
+        initialize_hosts
+        @hosts.map(&:deep_dup)
+      end
+
+      # Returns the cluster ID. Since this is a static provider with no cluster awareness,
+      # returns a placeholder value.
+      # @return [String]
+      def cluster_id
+        '<none>'
+      end
+
+      # No-op — there is no monitor to stop for this host list provider.
+      def stop_monitor; end
+
+      private
+
+      def initialize_hosts
+        return if @initialized
+
+        connection_service = @service_container.connection_service
+        config = connection_service.config
+        @hosts = if config.multi_host_url?
+                   build_multi_host_list(config.original_host, config.original_port)
+                 else
+                   [connection_service.initial_host_info]
+                 end
+        @initialized = true
+      end
+
+      def build_multi_host_list(original_host, original_port)
+        hosts = original_host.split(',').map(&:strip)
+        port_str = original_port.to_s
+
+        # If a single port is specified (no commas), it applies to all hosts.
+        # If commas are present, each port maps positionally to each host (empty entries become NO_PORT).
+        single_port = !port_str.include?(',')
+        ports = port_str.split(',', -1)
+
+        hosts.each_with_index.map do |host, i|
+          port_value = if single_port
+                         port_str.strip.empty? ? HostInfo::NO_PORT : port_str.strip
+                       else
+                         port = ports[i]&.strip
+                         port.nil? || port.empty? ? HostInfo::NO_PORT : port
+                       end
+          HostInfo.new(host:, port: port_value, role: HostRole::UNKNOWN)
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/host/global_aurora_host_list_provider.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 'rds_host_list_provider'
+require_relative '../monitoring/global_cluster_topology_monitor'
+require_relative '../property_definition'
+
+module AwsAdvancedRubyDriverWrapper
+  module Host
+    # Host list provider for Aurora Global Database clusters.
+    # Extends RdsHostListProvider with multi-region instance templates
+    # and uses GlobalClusterTopologyMonitor.
+    class GlobalAuroraHostListProvider < RdsHostListProvider
+      attr_reader :instance_templates_by_region
+
+      def initialize(service_container:, topology_utils:)
+        super
+        @instance_templates_by_region = build_instance_templates_by_region
+      end
+
+      def force_refresh(verify_writer, timeout_sec)
+        monitor = @service_container.monitor_service.run_if_absent(:cluster_topology, @cluster_id, @service_container) do |_sc|
+          Monitoring::GlobalClusterTopologyMonitor.new(
+            service_container: @service_container,
+            cluster_id: @cluster_id,
+            instance_template: @instance_template,
+            instance_templates_by_region: @instance_templates_by_region,
+            topology_utils: @topology_utils,
+            monitoring_driver_props: @monitoring_driver_props,
+            monitoring_wrapper_props: @monitoring_wrapper_props
+          )
+        end
+        monitor.force_refresh(verify_writer, timeout_sec)
+      rescue Timeout::Error
+        nil
+      end
+
+      private
+
+      def build_instance_templates_by_region
+        props = @service_container.connection_service.wrapper_props
+        patterns_str = PropertyDefinition::GLOBAL_CLUSTER_INSTANCE_HOST_PATTERNS.get(props)
+        unless patterns_str
+          raise Errors::AwsError,
+                "#{PropertyDefinition::GLOBAL_CLUSTER_INSTANCE_HOST_PATTERNS.name} is required for Global Aurora Databases"
+        end
+
+        @topology_utils.parse_instance_templates(patterns_str, method(:validate_host_pattern!))
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/host/host_availability.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 AwsAdvancedRubyDriverWrapper
+  module Host
+    module HostAvailability
+      AVAILABLE = :available
+      UNAVAILABLE = :unavailable
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/host/host_availability_strategy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 AwsAdvancedRubyDriverWrapper
+  module Host
+    class HostAvailabilityStrategy
+      def host_availability(raw_host_availability) = raw_host_availability
+
+      def host_availability=(_host_availability)
+        # Intentionally do nothing.
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/host/host_info.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 'host_availability'
+require_relative 'host_availability_strategy'
+require_relative 'host_role'
+
+module AwsAdvancedRubyDriverWrapper
+  module Host
+    class HostInfo
+      NO_PORT = '-1'
+      NO_HOST = ''
+      DEFAULT_WEIGHT = 100
+
+      # The attributes that define this host's identity, and that {#==} and {#hash} are derived from. They are
+      # read-only so that the hash code of an instance cannot change while it is held in a Hash or Set, which
+      # would otherwise make the instance impossible to look up. Use {#deep_dup} to obtain a copy with
+      # different values.
+      attr_reader :host, :port, :role
+
+      attr_accessor :availability_strategy, :weight, :id, :last_update_time
+
+      def initialize(
+        host: NO_HOST,
+        port: NO_PORT,
+        role: HostRole::WRITER,
+        availability: HostAvailability::AVAILABLE,
+        availability_strategy: HostAvailabilityStrategy.new,
+        weight: DEFAULT_WEIGHT,
+        id: nil,
+        last_update_time: nil
+      )
+        @host = host
+        @port = port
+        @role = role
+        @availability = availability
+        @availability_strategy = availability_strategy
+        @weight = weight
+        @id = id
+        @last_update_time = last_update_time
+      end
+
+      def ==(other)
+        return true if equal?(other)
+        return false unless other.is_a?(HostInfo)
+
+        host == other.host &&
+          port == other.port &&
+          role == other.role
+      end
+
+      alias eql? ==
+
+      def hash
+        [host, port, role].hash
+      end
+
+      def to_s
+        "HostInfo(#{host}, #{port}, #{role}, #{availability})"
+      end
+
+      def inspect
+        to_s
+      end
+
+      # Returns a deep copy of this HostInfo, duplicating all mutable fields. Since {#host}, {#port} and {#role}
+      # are read-only, this is also the way to obtain an instance that differs from this one in any of them.
+      #
+      # @param host [String] the host of the copy, defaulting to this host's.
+      # @param port [String] the port of the copy, defaulting to this host's.
+      # @param role [Symbol] the role of the copy, defaulting to this host's.
+      # @return [HostInfo]
+      def deep_dup(host: self.host, port: self.port, role: self.role)
+        HostInfo.new(
+          host: host.dup,
+          port: port.dup,
+          role:,
+          availability:,
+          weight:,
+          id: id&.dup,
+          last_update_time:
+        )
+      end
+
+      def url
+        "#{host_and_port}/"
+      end
+
+      def host_and_port
+        port_specified? ? "#{host}:#{port}" : host
+      end
+
+      def port_specified?
+        port != NO_PORT
+      end
+
+      def host_specified?
+        !host.nil? && host != NO_HOST
+      end
+
+      # Returns the availability of this host.
+      #
+      # @return [Symbol] either {HostAvailability::AVAILABLE} or {HostAvailability::UNAVAILABLE}
+      def availability
+        return availability_strategy.host_availability(@availability) if availability_strategy
+
+        @availability
+      end
+
+      def availability=(availability)
+        @availability = availability
+        availability_strategy&.host_availability = availability
+      end
+
+      # Returns the raw availability of this host.
+      #
+      # @return [Symbol] the raw availability of this host, ignoring the
+      #   {#availability_strategy} if it has one.
+      def raw_availability
+        @availability
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/host/host_role.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 AwsAdvancedRubyDriverWrapper
+  module Host
+    module HostRole
+      UNKNOWN = :unknown
+      READER = :reader
+      WRITER = :writer
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/host/random_host_selector.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  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
+#
+#  http://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 AwsAdvancedRubyDriverWrapper
+  module Host
+    class RandomHostSelector
+      STRATEGY_NAME = 'random'
+
+      # Selects a random available host matching the requested role from the given host list.
+      #
+      # @param hosts [Array<HostInfo>] list of available hosts to pick from.
+      # @param role [Symbol, nil] the desired host role, or nil for no preference.
+      # @param _props [Hash, nil] connection properties.
+      # @return [HostInfo, nil] an available host matching the requested role, or nil if none are eligible.
+      def select_host(hosts, role, _props = nil)
+        eligible_hosts = hosts.select do |host|
+          (role.nil? || host.role == role) &&
+            host.availability == HostAvailability::AVAILABLE
+        end
+
+        return nil if eligible_hosts.empty?
+
+        eligible_hosts.sample
+      end
+    end
+  end
+end