aws_advanced_ruby_driver_wrapper 1.0.0

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/phase_time_info.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.
+
+require_relative 'phase'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module BlueGreen
+      PhaseTimeInfo = Struct.new(:timestamp, :timestamp_nano, :phase)
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/role.rb

@@ -0,0 +1,38 @@
+# 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 Plugins
+    module BlueGreen
+      module Role
+        SOURCE = :source
+        TARGET = :target
+
+        ROLE_MAPPING_1_0 = {
+          'BLUE_GREEN_DEPLOYMENT_SOURCE' => SOURCE,
+          'BLUE_GREEN_DEPLOYMENT_TARGET' => TARGET
+        }.freeze
+
+        def self.parse_role(value, version)
+          raise ArgumentError, "Unknown Blue/Green version: #{version}" unless version == '1.0'
+          raise ArgumentError, 'Blue/Green role value is blank' if value.nil? || value.strip.empty?
+
+          ROLE_MAPPING_1_0.fetch(value.upcase) { raise ArgumentError, "Unknown Blue/Green role: #{value}" }
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/routing/base_routing.rb

@@ -0,0 +1,83 @@
+# 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 '../../../logging'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module BlueGreen
+      module Routing
+        module BaseRouting
+          include Logging
+
+          MINIMUM_SLEEP_CHUNK_SEC = 0.05
+
+          def match?(host_info, role)
+            (@host.nil? || @host.downcase == host_info&.host&.downcase) &&
+              (@port.nil? || @port == host_info&.port) &&
+              (@role.nil? || @role == role)
+          end
+
+          def to_s
+            "#{self.class.name.split('::').last}@#{object_id.to_s(16)} [" \
+              "host: #{@host || '<null>'}, " \
+              "port: #{@port || '<null>'}, " \
+              "role: #{@role || '<null>'}, " \
+              "bgd_id: #{defined?(@bgd_id) ? (@bgd_id || '<null>') : '<n/a>'}]"
+          end
+
+          # Blocks until the Blue/Green switchover phase is no longer IN_PROGRESS, or until the
+          # configured timeout elapses.
+          def wait_while_in_progress(wrapper_props, storage_service, bgd_id, sleep_time_sec = MINIMUM_SLEEP_CHUNK_SEC)
+            bg_status = storage_service.get(BlueGreenPlugin::BLUE_GREEN_NAME, bgd_id)
+            remaining_sec = PropertyDefinition::BG_CONNECT_TIMEOUT_SEC.get_float(wrapper_props)
+
+            while remaining_sec.positive? && bg_status&.current_phase == Phase::IN_PROGRESS
+              sleep_sec = [sleep_time_sec, remaining_sec].min
+              delay(sleep_sec, bg_status, storage_service, bgd_id)
+              remaining_sec -= sleep_sec
+              bg_status = storage_service.get(BlueGreenPlugin::BLUE_GREEN_NAME, bgd_id)
+            end
+
+            if bg_status&.current_phase == Phase::IN_PROGRESS
+              raise Errors::BlueGreenTimeoutError, yield(PropertyDefinition::BG_CONNECT_TIMEOUT_SEC.get_float(wrapper_props))
+            end
+
+            bg_status
+          end
+
+          protected
+
+          def delay(delay_sec, bg_status, storage_service, bgd_id)
+            if bg_status.nil?
+              sleep(delay_sec)
+            else
+              deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay_sec
+              min_delay = [delay_sec, MINIMUM_SLEEP_CHUNK_SEC].min
+
+              # Wake early if the status reference changes or the deadline passes.
+              # Thread interruption surfaces as Interrupt raised into bg_status.wait, unwinding the caller.
+              until Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline ||
+                    bg_status != storage_service.get(BlueGreenPlugin::BLUE_GREEN_NAME, bgd_id)
+                bg_status.wait(min_delay * 1000)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/routing/reject_connect_routing.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.
+
+require_relative '../../../errors'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module BlueGreen
+      module Routing
+        # Rejects any attempt to open a new connection during a Blue/Green switchover.
+        class RejectConnectRouting
+          include BaseRouting
+
+          def initialize(host, port, role)
+            @host = host
+            @port = port
+            @role = role
+          end
+
+          def apply(*, **)
+            raise Errors::BlueGreenSwitchoverError, 'Blue/Green Deployment switchover is in progress. New connection can\'t be opened.'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/routing/substitute_connect_routing.rb

@@ -0,0 +1,136 @@
+# 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 Plugins
+    module BlueGreen
+      module Routing
+        # Opens a new connection to a substitute host instead of the originally requested host.
+        # When IAM auth is active and the substitute host is an IP address, each configured IAM
+        # host is tried in turn so the IAM plugin can resolve the correct token hostname.
+        class SubstituteConnectRouting
+          include BaseRouting
+
+          def initialize(host, port, role, substitute_host, iam_hosts, iam_successful_connect_notify = nil)
+            @host = host
+            @port = port
+            @role = role
+            @substitute_host = substitute_host
+            @iam_hosts = iam_hosts
+            @iam_successful_connect_notify = iam_successful_connect_notify
+          end
+
+          def to_s
+            port_str = @port ? ":#{@port}" : ''
+            iam_hosts_str = @iam_hosts&.map(&:host_and_port)&.join(', ') || '<null>'
+            "#{self.class.name.split('::').last}@#{object_id.to_s(16)} [" \
+              "#{@host}#{port_str}, " \
+              "role: #{@role}, " \
+              "substitute: #{@substitute_host&.host_and_port || '<null>'}, " \
+              "iam_hosts: #{iam_hosts_str}]"
+          end
+
+          def apply(_host_info,
+                    driver_props,
+                    wrapper_props,
+                    is_initial_connection,
+                    service_container,
+                    is_internal: false,
+                    bg_plugin: nil)
+            plugin_manager = service_container.plugin_manager
+            dialect_service = service_container.dialect_service
+
+            unless Utils::RdsUtils.ip?(@substitute_host.host)
+              return open_connection(plugin_manager, @substitute_host, driver_props, wrapper_props, is_initial_connection, is_internal,
+                                     bg_plugin)
+            end
+
+            # mysql2 uses :host for both socket connection and TLS CN verification.
+            # Connecting to a raw IP with TLS active causes a CN mismatch.
+            # Fall back to connecting via hostname (DNS will resolve to the correct IP post-switchover),
+            # matching the effective behaviour of the Java/Go MySQL drivers which use the original
+            # hostname for TLS regardless of the socket address.
+            if driver_props[:sslca] && !plugin_manager.plugin_in_use?(Plugins::IamAuthPlugin)
+              hostname_host = @substitute_host.deep_dup(host: @host)
+              return open_connection(plugin_manager, hostname_host, driver_props, wrapper_props, is_initial_connection, is_internal,
+                                     bg_plugin)
+            end
+
+            if plugin_manager.plugin_in_use?(Plugins::IamAuthPlugin)
+              if @iam_hosts.nil? || @iam_hosts.empty?
+                raise StandardError,
+                      'Connecting with IP address when IAM authentication is enabled requires an \'iam_host\' parameter.'
+              end
+
+              @iam_hosts.each do |iam_host|
+                rerouted_host = @substitute_host.deep_dup
+                rerouted_host.id = iam_host.id
+                rerouted_host.availability = Host::HostAvailability::AVAILABLE
+
+                rerouted_wrapper_props = wrapper_props.dup
+                PropertyDefinition::IAM_HOST.set(rerouted_wrapper_props, iam_host.host)
+                PropertyDefinition::IAM_PORT.set(rerouted_wrapper_props, iam_host.port.to_s) if iam_host.port_specified?
+
+                begin
+                  conn = plugin_manager.internal_connect(
+                    rerouted_host,
+                    driver_props,
+                    rerouted_wrapper_props,
+                    is_initial_connection,
+                    plugin_to_skip: bg_plugin
+                  )
+                  begin
+                    @iam_successful_connect_notify&.call(iam_host.host)
+                  rescue StandardError
+                    nil
+                  end
+                  return conn
+                rescue StandardError => e
+                  raise unless dialect_service.login_error?(e)
+                end
+              end
+              return nil
+            end
+
+            open_connection(plugin_manager, @substitute_host, driver_props, wrapper_props, is_initial_connection, is_internal, bg_plugin)
+          rescue StandardError => e
+            raise unless dialect_service.login_error?(e)
+
+            nil
+          end
+
+          private
+
+          # Opens a connection through the plugin pipeline. Monitoring connections (is_internal: true)
+          # must use internal_connect so they do NOT mutate the shared current connection — otherwise
+          # one monitor thread's connect would close another monitor thread's live connection via
+          # update_current_connection, causing a use-after-free segfault in the mysql2 C extension.
+          #
+          # bg_plugin is skipped in the nested pipeline so this substitute connection does not re-enter
+          # BG routing. Without it, during the switchover window the opened connection matches the same
+          # routing again and recurses until the stack overflows (SystemStackError).
+          def open_connection(plugin_manager, host, driver_props, wrapper_props, is_initial_connection, is_internal, bg_plugin = nil)
+            if is_internal
+              plugin_manager.internal_connect(host, driver_props, wrapper_props, is_initial_connection, plugin_to_skip: bg_plugin)
+            else
+              plugin_manager.connect(host, driver_props, is_initial_connection, plugin_to_skip: bg_plugin)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/routing/suspend_connect_routing.rb

@@ -0,0 +1,53 @@
+# 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 Plugins
+    module BlueGreen
+      module Routing
+        class SuspendConnectRouting
+          include BaseRouting
+
+          SLEEP_TIME_SEC = 0.1
+
+          def initialize(host, port, role, bgd_id)
+            @host = host
+            @port = port
+            @role = role
+            @bgd_id = bgd_id
+          end
+
+          # Blocks until switchover is no longer IN_PROGRESS
+          def apply(_host_info, _, wrapper_props, _is_initial_connection, service_container, is_internal: false, bg_plugin: nil)
+            storage_service = service_container.storage_service
+            hold_start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+            wait_while_in_progress(wrapper_props, storage_service, @bgd_id, SLEEP_TIME_SEC) do |timeout_sec|
+              "Blue/Green Deployment switchover is still in progress after #{timeout_sec} s. Try to connect again later."
+            end
+
+            elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - hold_start_time) * 1000).round
+            logger.debug do
+              "Blue/Green Deployment switchover is completed. Continue with connect call. The call was held for #{elapsed_ms} ms."
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/routing/suspend_execute_routing.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.
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module BlueGreen
+      module Routing
+        class SuspendExecuteRouting
+          include BaseRouting
+
+          SLEEP_TIME_SEC = 0.1
+
+          def initialize(host, port, role, bgd_id)
+            @host = host
+            @port = port
+            @role = role
+            @bgd_id = bgd_id
+          end
+
+          # Blocks until switchover is no longer IN_PROGRESS
+          def apply(method_name, wrapper_props, storage_service)
+            hold_start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+            wait_while_in_progress(wrapper_props, storage_service, @bgd_id, SLEEP_TIME_SEC) do |timeout_sec|
+              "Blue/Green Deployment switchover is still in progress after #{timeout_sec} s. Try '#{method_name}' again later."
+            end
+
+            elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - hold_start_time) * 1000).round
+            logger.debug do
+              "Blue/Green Deployment switchover is completed. Continue with '#{method_name}' call. The call was held for #{elapsed_ms} ms."
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/routing/suspend_until_corresponding_host_found_connect_routing.rb

@@ -0,0 +1,83 @@
+# 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 Plugins
+    module BlueGreen
+      module Routing
+        # Suspends a new connection attempt until a corresponding green host is found for the
+        # requested host, or until the switchover completes.
+        class SuspendUntilCorrespondingHostFoundConnectRouting
+          include BaseRouting
+
+          SLEEP_TIME_SEC = 0.1
+
+          def initialize(host, port, role, bgd_id)
+            @host = host
+            @port = port
+            @role = role
+            @bgd_id = bgd_id
+          end
+
+          # Blocks until a corresponding green host is found for host_info.host, the switchover
+          # completes, or the timeout elapses.
+          def apply(host_info, _, wrapper_props, _is_initial_connection, service_container, is_internal: false, bg_plugin: nil)
+            storage_service = service_container.storage_service
+
+            bg_status = storage_service.get(BlueGreenPlugin::BLUE_GREEN_NAME, @bgd_id)
+            corresponding_pair = bg_status&.corresponding_hosts&.[](host_info.host)
+
+            timeout_sec = PropertyDefinition::BG_CONNECT_TIMEOUT_SEC.get_float(wrapper_props)
+            hold_start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            end_time = hold_start_time + timeout_sec
+
+            # Wait until a corresponding host is found, or until switchover is completed.
+            while Process.clock_gettime(Process::CLOCK_MONOTONIC) <= end_time &&
+                  !bg_status.nil? &&
+                  bg_status.current_phase != Phase::COMPLETED &&
+                  (corresponding_pair.nil? || corresponding_pair[1].nil?)
+              delay(SLEEP_TIME_SEC, bg_status, storage_service, @bgd_id)
+              bg_status = storage_service.get(BlueGreenPlugin::BLUE_GREEN_NAME, @bgd_id)
+              corresponding_pair = bg_status&.corresponding_hosts&.[](host_info.host)
+            end
+
+            elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - hold_start_time) * 1000).round
+
+            if bg_status.nil? || bg_status.current_phase == Phase::COMPLETED
+              logger.debug do
+                "Blue/Green Deployment status is completed. Continue with 'connect' call. The call was held for #{elapsed_ms} ms."
+              end
+              return nil
+            end
+
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) > end_time
+              raise Errors::BlueGreenTimeoutError,
+                    'Blue/Green Deployment switchover is still in progress and a corresponding ' \
+                    "host for '#{host_info.host}' is not found after " \
+                    "#{PropertyDefinition::BG_CONNECT_TIMEOUT_SEC.get_float(wrapper_props)} s. Try to connect again later."
+            end
+
+            logger.debug do
+              "A corresponding host for '#{host_info.host}' is found. Continue with connect call. The call was held for #{elapsed_ms} ms."
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/status.rb

@@ -0,0 +1,68 @@
+# 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 'concurrent'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module BlueGreen
+      class Status
+        attr_reader :bgd_id, :current_phase, :connect_routing, :execute_routing, :role_by_host, :corresponding_hosts
+
+        def initialize(bgd_id, phase, connect_routing: [], execute_routing: [], role_by_host: {}, corresponding_hosts: {})
+          @bgd_id = bgd_id
+          @current_phase = phase
+          @connect_routing = connect_routing.freeze
+          @execute_routing = execute_routing.freeze
+          @role_by_host = role_by_host.dup.freeze
+          @corresponding_hosts = corresponding_hosts.dup.freeze
+          @event = Concurrent::Event.new
+        end
+
+        def wait(timeout_ms)
+          @event.wait(timeout_ms / 1000.0)
+        end
+
+        def notify
+          @event.set
+        end
+
+        def role(host_spec)
+          @role_by_host[host_spec.host.downcase]
+        end
+
+        def to_s
+          role_map = @role_by_host.map { |k, v| "#{k} -> #{v}" }.join("\n")
+          connect_str = @connect_routing.join("\n")
+          execute_str = @execute_routing.join("\n")
+
+          <<~STATUS
+            Status [
+             bgd_id: '#{@bgd_id}',
+             phase: #{@current_phase},
+             Connect routing:
+               #{connect_str.empty? ? '-' : connect_str}
+             Execute routing:
+               #{execute_str.empty? ? '-' : execute_str}
+             role_by_host:
+               #{role_map.empty? ? '-' : role_map}
+            ]
+          STATUS
+        end
+      end
+    end
+  end
+end