aws_advanced_ruby_driver_wrapper 1.0.0

data/lib/aws_advanced_ruby_driver_wrapper/services/plugin_call_context.rb

@@ -0,0 +1,63 @@
+# 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 Services
+    # What a plugin can learn about, and change about, the call it is currently handling.
+    #
+    # A plugin's +execute+ already receives the arguments and the block of the call, but only as
+    # copies: the pipeline reads what it hands to the next plugin from here, so a plugin that needs
+    # to change them has to replace {#args} or {#block} rather than modify what it was given.
+    # Likewise {#sql} is not always among the arguments, since a result method has no SQL of its
+    # own and a prepared statement only carries the name it was prepared under.
+    #
+    # This context belongs to a single call on a single thread, and is reached through
+    # {PluginManager#current_call_context}.
+    class PluginCallContext
+      # @return [String, nil] the SQL the call originated from, nil when the caller could not say
+      attr_reader :sql
+
+      # @return [Array] the arguments the target driver method will be called with
+      attr_accessor :args
+
+      # @return [Proc, nil] the block the target driver method will be called with
+      attr_accessor :block
+
+      # @param sql [String, nil]
+      # @param args [Array]
+      # @param block [Proc, nil]
+      # @param field_names [Array<String>, Proc, nil] the result's column names in order, or a
+      #   callable that produces them; see {#field_names}
+      def initialize(sql, args, block = nil, field_names = nil)
+        @sql = sql
+        @args = args
+        @block = block
+        @field_names = field_names
+      end
+
+      # The result's column names, in order, for a plugin that reads rows as bare arrays of values
+      # and has to match each position back to a column. Only result methods supply it, and only
+      # when a plugin might need it, so it is resolved lazily and remembered: a call that never asks
+      # pays nothing, and one that asks more than once pays once.
+      #
+      # @return [Array<String>, nil] nil when the call carries no column names
+      def field_names
+        @field_names = @field_names.call if @field_names.respond_to?(:call)
+        @field_names
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/services/plugin_manager.rb

@@ -0,0 +1,273 @@
+# 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 'logger'
+require_relative '../errors'
+require_relative '../property_definition'
+require_relative '../ruby_method'
+require_relative '../utils/sql_encoding'
+require_relative '../plugins/default_plugin'
+require_relative '../plugins/failover_plugin'
+require_relative '../plugins/gdb/gdb_failover_plugin'
+require_relative '../plugins/iam_auth_plugin'
+require_relative '../plugins/initial_connection_strategy_plugin'
+require_relative '../plugins/kms_encryption/kms_encryption_plugin'
+require_relative '../plugins/secrets_manager_plugin'
+require_relative '../plugins/blue_green/blue_green_plugin'
+require_relative '../plugins/custom_endpoint/custom_endpoint_plugin'
+require_relative 'plugin_call_context'
+
+module AwsAdvancedRubyDriverWrapper
+  module Services
+    class PluginManager
+      WEIGHT_RELATIVE_TO_PRIOR_PLUGIN = -1
+      NOOP_CALLABLE = -> {}.freeze
+      CURRENT_CALL_CONTEXT_KEY = :aws_ruby_wrapper_plugin_call_context
+      private_constant :WEIGHT_RELATIVE_TO_PRIOR_PLUGIN, :NOOP_CALLABLE, :CURRENT_CALL_CONTEXT_KEY
+
+      @plugin_classes = {
+        'bg' => Plugins::BlueGreen::BlueGreenPlugin,
+        'custom_endpoint' => Plugins::CustomEndpoint::CustomEndpointPlugin,
+        'failover' => Plugins::FailoverPlugin,
+        'gdb_failover' => Plugins::Gdb::GdbFailoverPlugin,
+        'iam' => Plugins::IamAuthPlugin,
+        'initial_connection' => Plugins::InitialConnectionStrategyPlugin,
+        'kms_encryption' => Plugins::KmsEncryptionPlugin,
+        'secrets_manager' => Plugins::SecretsManagerPlugin
+      }
+
+      # The final list of plugins will be sorted by weight, starting from the lowest values up to
+      # the highest values. The first plugin of the list will have the lowest weight, and the
+      # last one will have the highest weight.
+      @plugin_weights = {
+        Plugins::BlueGreen::BlueGreenPlugin => 200,
+        Plugins::CustomEndpoint::CustomEndpointPlugin => 250,
+        Plugins::InitialConnectionStrategyPlugin => 300,
+        Plugins::FailoverPlugin => 400,
+        Plugins::Gdb::GdbFailoverPlugin => 500,
+        Plugins::IamAuthPlugin => 1800,
+        Plugins::SecretsManagerPlugin => 1900,
+        Plugins::KmsEncryptionPlugin => 2050
+      }
+
+      class << self
+        def register_plugin(plugin_code, plugin_class, weight: WEIGHT_RELATIVE_TO_PRIOR_PLUGIN)
+          @plugin_classes[plugin_code] = plugin_class
+          @plugin_weights[plugin_class] = weight
+        end
+
+        attr_reader :plugin_classes, :plugin_weights
+      end
+
+      def initialize(service_container)
+        @plugins = load_plugins(service_container)
+        @pipeline_cache = {}
+      end
+
+      def connect(host_info, driver_props, is_initial_connection, plugin_to_skip: nil)
+        execute_with_subscribed_plugins(
+          'connect',
+          lambda do |plugin, next_plugin_callable|
+            plugin.connect(host_info, driver_props, is_initial_connection, next_plugin_callable)
+          end,
+          NOOP_CALLABLE,
+          plugin_to_skip:
+        )
+      end
+
+      def internal_connect(host_info, driver_props, wrapper_props, is_initial_connection, plugin_to_skip: nil)
+        execute_with_subscribed_plugins(
+          'internal_connect',
+          lambda do |plugin, next_plugin_callable|
+            plugin.internal_connect(host_info, driver_props, wrapper_props, is_initial_connection, next_plugin_callable)
+          end,
+          NOOP_CALLABLE,
+          plugin_to_skip:
+        )
+      end
+
+      # The context of the call currently being executed, for plugins that need to know more about
+      # it than their own arguments say, or that need to change the arguments the target driver
+      # method is called with. See {PluginCallContext}.
+      #
+      # The context belongs to the calling thread and is restored when the call returns, so nested
+      # calls cannot see one another's.
+      #
+      # @return [PluginCallContext, nil] nil outside of a call
+      def current_call_context
+        Thread.current[CURRENT_CALL_CONTEXT_KEY]
+      end
+
+      # @return [String, nil] the SQL the call currently being executed originated from
+      def current_sql
+        current_call_context&.sql
+      end
+
+      # @param sql [String, nil] the SQL the call originated from, for plugins that inspect
+      #   statements; it is published as valid UTF-8 (see {Utils::SqlEncoding.inspectable}), and is
+      #   consumed here and never forwarded to the target driver method. Since invalid bytes in the
+      #   published copy are replaced, a plugin that rewrites the SQL builds the new statement from
+      #   the call's arguments rather than from this copy
+      # @param field_names [Array<String>, Proc, nil] the result's column names in order, for a
+      #   plugin that reads rows as arrays; like +sql+, it is consumed here rather than forwarded
+      def execute(ruby_method, current_conn, target_callable, *args, bounded_conn: nil, sql: nil, field_names: nil, **kwargs, &block)
+        if ruby_method.is_a?(MethodInfo)
+          method_name = ruby_method.name
+
+          if ruby_method.check_bounded_connection && !bounded_conn.nil? && !current_conn.nil? && (bounded_conn != current_conn)
+            raise Errors::AwsError, "Method invoked against old connection: #{bounded_conn}"
+          end
+        else
+          # Fallback for dynamic method names (method_missing with string)
+          method_name = ruby_method.to_s
+        end
+
+        context = PluginCallContext.new(Utils::SqlEncoding.inspectable(sql), args, block, field_names)
+        previous_context = Thread.current[CURRENT_CALL_CONTEXT_KEY]
+        Thread.current[CURRENT_CALL_CONTEXT_KEY] = context
+
+        begin
+          execute_with_subscribed_plugins(
+            method_name,
+            lambda do |plugin, next_plugin_callable|
+              # Read from the context rather than from args and block, so that a plugin which
+              # replaced either is honoured by the plugins after it and by the target method.
+              plugin.execute(method_name, next_plugin_callable, *context.args, **kwargs, &context.block)
+            end,
+            target_callable
+          )
+        ensure
+          Thread.current[CURRENT_CALL_CONTEXT_KEY] = previous_context
+        end
+      end
+
+      def num_plugins
+        @plugins&.length || 0
+      end
+
+      def plugin_in_use?(plugin_class)
+        return false if @plugins.nil? || @plugins.empty?
+
+        @plugins.any?(plugin_class)
+      end
+
+      private
+
+      def load_plugins(service_container)
+        wrapper_props = service_container.connection_service.wrapper_props
+        plugin_codes = PropertyDefinition::PLUGINS.get(wrapper_props)
+        codes_list = plugin_codes.split(',').map(&:strip)
+        ensure_single_auth_plugin(codes_list)
+        ensure_single_failover_plugin(codes_list)
+        raise Errors::AwsError, 'Duplicate plugins detected' if codes_list.length != codes_list.uniq.length
+
+        plugin_classes = plugin_codes.empty? ? [] : get_plugin_classes(codes_list, wrapper_props)
+
+        plugins = plugin_classes.map do |plugin_class|
+          plugin_class.new(service_container, wrapper_props)
+        end
+
+        plugins << Plugins::DefaultPlugin.new(service_container, wrapper_props)
+        plugins
+      end
+
+      def ensure_single_auth_plugin(plugin_code_list)
+        auth_plugins_used = plugin_code_list & %w[iam secrets_manager].freeze
+
+        return unless auth_plugins_used.length > 1
+
+        raise Errors::PluginConflictError,
+              "Only one authentication plugin may be used at a time. Found: #{auth_plugins_used.join(', ')}"
+      end
+
+      def ensure_single_failover_plugin(plugin_code_list)
+        failover_plugins_used = plugin_code_list & %w[failover gdb_failover].freeze
+
+        return unless failover_plugins_used.length > 1
+
+        raise Errors::PluginConflictError,
+              "Only one failover plugin may be used at a time. Found: #{failover_plugins_used.join(', ')}"
+      end
+
+      def get_plugin_classes(plugin_code_list, _wrapper_props)
+        plugin_classes = plugin_code_list.map do |plugin_code|
+          plugin_class = self.class.plugin_classes[plugin_code]
+          raise Errors::AwsError, "Invalid plugin: #{plugin_code}" if plugin_class.nil?
+
+          plugin_class
+        end
+
+        return [] if plugin_classes.empty?
+
+        weights = plugin_weights_for(plugin_classes)
+        plugin_classes.sort_by! { |ft| weights[ft] }
+
+        plugin_classes
+      end
+
+      def plugin_weights_for(plugin_classes)
+        last_weight = 0
+        plugin_classes.each_with_object({}) do |plugin_class, weights|
+          weight = self.class.plugin_weights[plugin_class]
+
+          if weight.nil? || weight == WEIGHT_RELATIVE_TO_PRIOR_PLUGIN
+            last_weight += 1
+            weights[plugin_class] = last_weight
+          else
+            weights[plugin_class] = weight
+            last_weight = weight
+          end
+        end
+      end
+
+      def execute_with_subscribed_plugins(
+        target_method_name,
+        plugin_callable,
+        target_driver_callable,
+        plugin_to_skip: nil
+      )
+        pipeline_callable = @pipeline_cache[target_method_name] ||= make_pipeline(target_method_name)
+        pipeline_callable.call(plugin_callable, target_driver_callable, target_method_name, plugin_to_skip)
+      end
+
+      # Builds the plugin pipeline function chain. The pipeline allows plugins to perform logic both before and after
+      # the target driver function is called.
+      def make_pipeline(target_method_name)
+        subscribed_plugins = @plugins.select do |p|
+          p.subscribed_methods.include?('*') || p.subscribed_methods.include?(target_method_name)
+        end
+        raise Errors::AwsError, 'Plugin pipeline is nil' if subscribed_plugins.empty?
+
+        base_plugin = subscribed_plugins.last
+        base = lambda do |plugin_callable, target_driver_callable, *, **|
+          plugin_callable.call(base_plugin, target_driver_callable)
+        end
+
+        subscribed_plugins[0...-1].reverse.reduce(base) do |next_plugin_callable, plugin|
+          lambda do |plugin_callable, target_driver_callable, method_name, plugin_to_skip|
+            if plugin_to_skip == plugin
+              next_plugin_callable.call(plugin_callable, target_driver_callable, method_name, plugin_to_skip)
+            else
+              plugin_callable.call(plugin, lambda do
+                next_plugin_callable.call(plugin_callable, target_driver_callable, method_name, plugin_to_skip)
+              end)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/services/service_container.rb

@@ -0,0 +1,30 @@
+# 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 Services
+    ServiceContainer = Struct.new(
+      :connection_service,
+      :dialect_service,
+      :event_publisher,
+      :host_service,
+      :plugin_manager,
+      :session_state_service,
+      :storage_service,
+      :monitor_service
+    )
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/services/service_utility.rb

@@ -0,0 +1,78 @@
+# 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 'service_container'
+require_relative 'connection_service'
+require_relative 'dialect_service'
+require_relative 'host_service'
+require_relative 'plugin_manager'
+require_relative 'monitor_service'
+require_relative 'session_state_service'
+require_relative '../utils/storage/storage_service'
+require_relative '../utils/events/batching_event_publisher'
+
+module AwsAdvancedRubyDriverWrapper
+  module Services
+    # Manages shared singleton services with correct dependency order.
+    # Initialized eagerly at require-time to avoid thread-safety races.
+    module CoreServices
+      @event_publisher = Utils::Events::BatchingEventPublisher.new
+      @storage_service = Utils::Storage::StorageService.new(event_publisher: @event_publisher)
+      @monitor_service = MonitorService.new(event_publisher: @event_publisher)
+
+      class << self
+        attr_reader :event_publisher, :storage_service, :monitor_service
+      end
+
+      # Resets all shared instances. For testing only.
+      # @api private
+      def self.reset!
+        @monitor_service.shutdown(grace_period: 2)
+        @storage_service.shutdown
+        @event_publisher.release_resources
+        @event_publisher = Utils::Events::BatchingEventPublisher.new
+        @storage_service = Utils::Storage::StorageService.new(event_publisher: @event_publisher)
+        @monitor_service = MonitorService.new(event_publisher: @event_publisher)
+      end
+    end
+
+    module ServiceUtility
+      def self.create_standard_container(config)
+        container = ServiceContainer.new
+        container.event_publisher = CoreServices.event_publisher
+        container.connection_service = ConnectionService.new(container, config)
+        container.dialect_service = DialectService.new(container.connection_service, config.driver_name)
+        container.host_service = HostService.new(container)
+        container.session_state_service = SessionStateService.new
+        container.storage_service = CoreServices.storage_service
+        container.monitor_service = CoreServices.monitor_service
+        # PluginManager must be assigned last: plugins are instantiated during its constructor
+        # and must not eagerly access container.plugin_manager (it will be nil at that point).
+        container.plugin_manager = PluginManager.new(container)
+        container.dialect_service.setup_initial_provider(container)
+        container
+      end
+
+      def self.create_monitor_container(parent_container)
+        container = ServiceContainer.new
+        container.event_publisher = parent_container.event_publisher
+        container.dialect_service = parent_container.dialect_service
+        container.host_service = parent_container.host_service
+        container
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/services/session_state_service.rb

@@ -0,0 +1,56 @@
+# 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 '../utils/sql_method_analyzer'
+
+module AwsAdvancedRubyDriverWrapper
+  module Services
+    class SessionStateService
+      attr_accessor :in_transaction, :autocommit
+      alias in_transaction? in_transaction
+      alias autocommit? autocommit
+
+      def initialize
+        reset
+      end
+
+      def reset
+        @in_transaction = false
+        @autocommit = true
+      end
+
+      def update_transaction_state(method_name, args, autocommit_before, dialect, connection, succeeded: true)
+        connection_in_transaction = dialect.reported_in_transaction(connection)
+        unless connection_in_transaction.nil?
+          self.in_transaction = connection_in_transaction
+          return
+        end
+        # When the statement failed, SQL inference can't tell what took effect, so keep the current state.
+        return unless succeeded
+
+        effect = Utils::SqlMethodAnalyzer.transaction_effect(
+          method_name, args, autocommit: autocommit?, autocommit_before: autocommit_before
+        )
+        if effect.opens_transaction
+          self.in_transaction = true
+        elsif effect.closes_transaction
+          self.in_transaction = false
+        end
+        self.autocommit = effect.autocommit_value unless effect.autocommit_value.nil?
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/accessible_regions.rb

@@ -0,0 +1,52 @@
+# 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 '../property_definition'
+require_relative 'rds_utils'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module AccessibleRegions
+      module_function
+
+      def parse(props)
+        value = PropertyDefinition::ACCESSIBLE_REGIONS.get(props)
+        return nil if value.nil? || value.strip.empty?
+
+        regions = value.split(',').map { |r| r.strip.downcase }.reject(&:empty?)
+
+        invalid = regions.reject { |r| RdsUtils.valid_region?(r) }
+        unless invalid.empty?
+          raise Errors::AwsError,
+                "#{PropertyDefinition::ACCESSIBLE_REGIONS.name} contains unknown or misspelled AWS " \
+                "region(s): #{invalid.join(', ')}"
+        end
+
+        regions.empty? ? nil : regions.to_set
+      end
+
+      def filter_by_region(hosts, accessible_regions)
+        return hosts if accessible_regions.nil?
+
+        hosts.select do |host|
+          region = RdsUtils.rds_region(host.host)
+          region && accessible_regions.include?(region.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/ar_constants.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 Utils
+    # ActiveRecord-only keys that should not be passed to the wrapper or native driver.
+    AR_COMMON_KEYS = %i[
+      adapter pool checkout_timeout idle_timeout reaping_frequency
+      variables prepared_statements encoding reconnect socket flags
+    ].freeze
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/aurora_topology_utils.rb

@@ -0,0 +1,99 @@
+# 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 'topology_utils'
+require_relative 'conversion_utils'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    # Topology utilities specific to Aurora database clusters.
+    # Processes topology query results that return instance ID, writer flag, CPU utilization, and instance lag columns.
+    class AuroraTopologyUtils
+      include TopologyUtils
+      include ConversionUtils
+
+      def initialize(dialect:)
+        raise ArgumentError, 'dialect cannot be nil' if dialect.nil?
+
+        @dialect = dialect
+      end
+
+      # Evaluate whether the given connection is to a writer instance.
+      #
+      # @param conn [Object] the connection to evaluate.
+      # @return [Boolean] true if the connection is to a writer instance, false otherwise.
+      def writer_instance?(conn)
+        results = @dialect.execute(conn, @dialect.writer_id_query)
+        return false if results.nil? || results.none?
+
+        row = results.first
+        !row.nil? && !row.values.first.nil? && !row.values.first.to_s.empty?
+      end
+
+      # Process Aurora topology query results into a list of HostInfo objects.
+      # Data in the result set is ordered by last update time, so the latest records are last.
+      # Newer records replace older ones if there are duplicate hosts.
+      #
+      # @param results [Object] the query result set (enumerable of row hashes).
+      # @param initial_host_info [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the initial host info.
+      # @param instance_template [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the template for building hosts.
+      # @return [Array<AwsAdvancedRubyDriverWrapper::Host::HostInfo>, nil] the parsed hosts or nil on failure.
+      def build_hosts(_conn, results, initial_host_info, instance_template)
+        hosts_map = {}
+
+        results.each do |row|
+          host = build_host_from_row(row, initial_host_info, instance_template)
+
+          # Ensure newer records replace the older ones if there are duplicate keys.
+          existing = hosts_map[host.host]
+          if existing.nil? || (existing.last_update_time && host.last_update_time &&
+              existing.last_update_time < host.last_update_time)
+            hosts_map[host.host] = host
+          end
+        rescue StandardError => e
+          logger.debug("Error processing topology query results: #{e.message}")
+          return nil
+        end
+
+        hosts_map.values
+      end
+
+      private
+
+      # Creates a HostInfo from a single Aurora topology query result row.
+      #
+      # According to the topology query, the result set should contain columns:
+      # host_id, is_writer, cpu_utilization, instance_lag, last_update_time.
+      #
+      # @param row [Hash] a single row from the topology query result.
+      # @param initial_host_info [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the initial host info.
+      # @param instance_template [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the template for building hosts.
+      # @return [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the constructed host info.
+      def build_host_from_row(row, initial_host_info, instance_template)
+        instance_id = row_value(row, 'instance_id')
+        is_writer = to_boolean(row_value(row, 'is_writer'))
+        cpu_utilization = to_float(row_value(row, 'cpu_utilization'))
+        instance_lag = to_float(row_value(row, 'instance_lag'))
+        last_update_time = to_time(row_value(row, 'last_update_time'))
+
+        # Calculate weight based on instance lag and CPU utilization.
+        weight = (instance_lag.round * 100) + cpu_utilization.round
+
+        build_host(instance_id, instance_id, is_writer, weight, last_update_time, initial_host_info, instance_template)
+      end
+    end
+  end
+end