aws_advanced_ruby_driver_wrapper 1.0.0

data/lib/aws_advanced_ruby_driver_wrapper/utils/rds_utils.rb

@@ -0,0 +1,575 @@
+# 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'
+require_relative 'rds_url_type'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    # Utility module for parsing and classifying Amazon RDS/Aurora endpoint hostnames.
+    #
+    # Determines endpoint type (writer cluster, reader cluster, instance, proxy, etc.),
+    # extracts metadata (region, cluster ID, instance ID), and supports blue/green
+    # deployment host manipulation.
+    #
+    # Aurora endpoint format reference:
+    #   https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.Overview.Endpoints.html
+    #
+    # Cluster (Writer):  <db-cluster>.cluster-<xyz>.<region>.rds.amazonaws.com
+    # Cluster Reader:    <db-cluster>.cluster-ro-<xyz>.<region>.rds.amazonaws.com
+    # Custom Cluster:    <alias>.cluster-custom-<xyz>.<region>.rds.amazonaws.com
+    # Instance:          <instance>.<xyz>.<region>.rds.amazonaws.com
+    # RDS Proxy:         <proxy>.proxy-<xyz>.<region>.rds.amazonaws.com
+    # RDS Proxy Custom:  <name>.endpoint.proxy-<xyz>.<region>.rds.amazonaws.com
+    # Global DB Writer:  <gdb>.global-<xyz>.global.rds.amazonaws.com
+    # Limitless:         <db>.shardgrp-<xyz>.<region>.rds.amazonaws.com
+    #
+    # China regions use a different structure:
+    #   New:  <xyz>.rds.<region>.amazonaws.com.cn
+    #   Old:  <xyz>.<region>.rds.amazonaws.com.cn
+    #
+    # Gov/ISO/ISOB regions:
+    #   <xyz>.(rds|rds-fips).<region>.(amazonaws.com|c2s.ic.gov|sc2s.sgov.gov)
+    module RdsUtils
+      extend self
+
+      # Authoritative allow-list of AWS regions that can host an RDS/Aurora endpoint.
+      KNOWN_REGIONS = %w[
+        af-south-1
+        ap-east-1 ap-east-2
+        ap-northeast-1 ap-northeast-2 ap-northeast-3
+        ap-south-1 ap-south-2
+        ap-southeast-1 ap-southeast-2 ap-southeast-3 ap-southeast-4
+        ap-southeast-5 ap-southeast-6 ap-southeast-7
+        ca-central-1 ca-west-1
+        cn-north-1 cn-northwest-1
+        eu-central-1 eu-central-2
+        eu-isoe-west-1
+        eu-north-1
+        eu-south-1 eu-south-2
+        eu-west-1 eu-west-2 eu-west-3
+        eusc-de-east-1
+        il-central-1
+        me-central-1 me-south-1
+        mx-central-1
+        sa-east-1
+        us-east-1 us-east-2
+        us-gov-east-1 us-gov-west-1
+        us-iso-east-1 us-iso-west-1
+        us-isob-east-1 us-isob-west-1
+        us-isof-east-1 us-isof-south-1
+        us-west-1 us-west-2
+      ].to_set.freeze
+
+      # -- Standard commercial regions --
+      AURORA_DNS_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>proxy-|cluster-|cluster-ro-|cluster-custom-|shardgrp-)?
+        (?<domain>[a-zA-Z0-9]+\.(?<region>[a-zA-Z0-9-]+)
+        \.(?:rds|rds-fips)\.amazonaws\.(?:com|au|eu|uk)\.?)$
+      /ix
+
+      AURORA_CLUSTER_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>cluster-|cluster-ro-)+
+        (?<domain>[a-zA-Z0-9]+\.(?<region>[a-zA-Z0-9-]+)
+        \.(?:rds|rds-fips)\.amazonaws\.(?:com|au|eu|uk)\.?)$
+      /ix
+
+      # -- Limitless (covers all TLD variants) --
+      AURORA_LIMITLESS_CLUSTER_PATTERN = /
+        (?<instance>.+)\.
+        (?<dns>shardgrp-)+
+        (?<domain>[a-zA-Z0-9]+\.(?<region>[a-zA-Z0-9-]+)
+        \.(?:rds|rds-fips)\.(?:amazonaws\.com\.?|amazonaws\.eu\.?|amazonaws\.au\.?|amazonaws\.uk\.?
+        |amazonaws\.com\.cn\.?|sc2s\.sgov\.gov\.?|c2s\.ic\.gov\.?))$
+      /ix
+
+      # -- China (new format: <xyz>.rds.<region>.amazonaws.com.cn) --
+      AURORA_CHINA_DNS_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>proxy-|cluster-|cluster-ro-|cluster-custom-|shardgrp-)?
+        (?<domain>[a-zA-Z0-9]+\.(?:rds|rds-fips)\.(?<region>[a-zA-Z0-9-]+)
+        \.amazonaws\.com\.cn\.?)$
+      /ix
+
+      AURORA_CHINA_CLUSTER_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>cluster-|cluster-ro-)+
+        (?<domain>[a-zA-Z0-9]+\.(?:rds|rds-fips)\.(?<region>[a-zA-Z0-9-]+)
+        \.amazonaws\.com\.cn\.?)$
+      /ix
+
+      # -- China (old/legacy format: <xyz>.<region>.rds.amazonaws.com.cn) --
+      AURORA_OLD_CHINA_DNS_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>proxy-|cluster-|cluster-ro-|cluster-custom-|shardgrp-)?
+        (?<domain>[a-zA-Z0-9]+\.(?<region>[a-zA-Z0-9-]+)
+        \.(?:rds|rds-fips)\.amazonaws\.com\.cn\.?)$
+      /ix
+
+      AURORA_OLD_CHINA_CLUSTER_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>cluster-|cluster-ro-)+
+        (?<domain>[a-zA-Z0-9]+\.(?<region>[a-zA-Z0-9-]+)
+        \.(?:rds|rds-fips)\.amazonaws\.com\.cn\.?)$
+      /ix
+
+      # -- Gov / ISO / ISOB regions --
+      AURORA_GOV_DNS_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>proxy-|cluster-|cluster-ro-|cluster-custom-|shardgrp-)?
+        (?<domain>[a-zA-Z0-9]+\.(?:rds|rds-fips)\.(?<region>[a-zA-Z0-9-]+)
+        \.(?:amazonaws\.com\.?|c2s\.ic\.gov\.?|sc2s\.sgov\.gov\.?))$
+      /ix
+
+      AURORA_GOV_CLUSTER_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>cluster-|cluster-ro-)+
+        (?<domain>[a-zA-Z0-9]+\.(?:rds|rds-fips)\.(?<region>[a-zA-Z0-9-]+)
+        \.(?:amazonaws\.com\.?|c2s\.ic\.gov\.?|sc2s\.sgov\.gov\.?))$
+      /ix
+
+      # -- ELB (region extraction only) --
+      ELB_PATTERN = /
+        ^(?<instance>.+)\.elb\.
+        (?<region>[a-zA-Z0-9-]+)\.amazonaws\.(?:com|au|eu|uk)\.?$
+      /ix
+
+      # -- IP addresses --
+      IP_V4 = /
+        ^(?:[1-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.
+        (?:(?:[0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){2}
+        (?:[0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
+      /x
+
+      IP_V6 = /^[0-9a-fA-F]{1,4}(?::[0-9a-fA-F]{1,4}){7}$/i
+
+      IP_V6_COMPRESSED = /
+        ^(?:[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,5})?
+        ::
+        (?:[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,5})?$
+      /ix
+
+      # -- Blue/green deployment --
+      BG_GREEN_HOST_PATTERN = /(?<prefix>-green-[0-9a-z]{6})\./i
+      BG_GREEN_HOSTID_PATTERN = /\A(.+)-green-[0-9a-z]{6}\z/i
+      BG_OLD_HOST_PATTERN = /(?<prefix>-old1)\./i
+
+      # -- Global database --
+      AURORA_GLOBAL_WRITER_DNS_PATTERN = /
+        ^(?<instance>.+)\.
+        (?<dns>global-)?
+        (?<domain>[a-zA-Z0-9]+\.global\.rds\.amazonaws\.com\.?)$
+      /ix
+
+      # -- RDS Proxy endpoints --
+      RDS_PROXY_ENDPOINT_DNS_PATTERN = /
+        ^(?<instance>.+)\.endpoint\.
+        (?<dns>proxy-)?
+        (?<domain>[a-zA-Z0-9]+\.(?<region>[a-zA-Z0-9-]+)
+        \.rds\.amazonaws\.com\.?)$
+      /ix
+
+      RDS_PROXY_ENDPOINT_CHINA_DNS_PATTERN = /
+        ^(?<instance>.+)\.endpoint\.
+        (?<dns>proxy-)+
+        (?<domain>[a-zA-Z0-9]+\.rds\.(?<region>[a-zA-Z0-9-]+)
+        \.amazonaws\.com\.cn\.?)$
+      /ix
+
+      RDS_PROXY_ENDPOINT_OLD_CHINA_DNS_PATTERN = /
+        ^(?<instance>.+)\.endpoint\.
+        (?<dns>proxy-)?
+        (?<domain>[a-zA-Z0-9]+\.(?<region>[a-zA-Z0-9-]+)
+        \.rds\.amazonaws\.com\.cn\.?)$
+      /ix
+
+      DNS_PATTERNS = [
+        AURORA_DNS_PATTERN,
+        AURORA_CHINA_DNS_PATTERN,
+        AURORA_OLD_CHINA_DNS_PATTERN,
+        AURORA_GOV_DNS_PATTERN
+      ].freeze
+
+      DNS_GROUP_PATTERNS = [
+        AURORA_DNS_PATTERN,
+        AURORA_CHINA_DNS_PATTERN,
+        AURORA_OLD_CHINA_DNS_PATTERN,
+        AURORA_GOV_DNS_PATTERN,
+        AURORA_GLOBAL_WRITER_DNS_PATTERN
+      ].freeze
+
+      CLUSTER_PATTERNS = [
+        [AURORA_CLUSTER_PATTERN, 'cluster-'],
+        [AURORA_CHINA_CLUSTER_PATTERN, 'cluster-'],
+        [AURORA_OLD_CHINA_CLUSTER_PATTERN, 'cluster-'],
+        [AURORA_GOV_CLUSTER_PATTERN, 'cluster-'],
+        [AURORA_LIMITLESS_CLUSTER_PATTERN, 'shardgrp-']
+      ].freeze
+
+      PROXY_ENDPOINT_PATTERNS = [
+        RDS_PROXY_ENDPOINT_DNS_PATTERN,
+        RDS_PROXY_ENDPOINT_CHINA_DNS_PATTERN,
+        RDS_PROXY_ENDPOINT_OLD_CHINA_DNS_PATTERN
+      ].freeze
+
+      # Caches the regex match groups per host. Only positive matches are ever stored (never nil),
+      # so a lock-free concurrent map is safe here and its reads avoid a mutex on the hot path.
+      @cached_matches = Concurrent::Map.new
+
+      # Caches the DNS-group token per host. Unlike the other two, this caches nil results (a host
+      # with no DNS group), which a concurrent map cannot hold, so it stays a plain hash guarded by
+      # @mutex.
+      @cached_dns_groups = {}
+      @mutex = Mutex.new
+      @prepare_host_func = nil
+
+      # Caches the final endpoint classification per host. Values are never nil, so like
+      # @cached_matches it uses a lock-free concurrent map; a hit skips the whole pattern sweep.
+      @cached_url_types = Concurrent::Map.new
+
+      def clear_cache
+        @cached_matches.clear
+        @cached_url_types.clear
+        @mutex.synchronize { @cached_dns_groups.clear }
+      end
+
+      attr_reader :prepare_host_func
+
+      # Changing how hosts are prepared can change their classification, so the classification cache
+      # (keyed by the raw host) must be dropped when the prepare function changes. The pattern caches
+      # are keyed by the prepared host and self-invalidate, so they do not need clearing here.
+      def prepare_host_func=(func)
+        @prepare_host_func = func
+        @cached_url_types.clear
+      end
+
+      def reset_prepare_host_func
+        @prepare_host_func = nil
+        @cached_url_types.clear
+      end
+
+      def rds_dns?(host)
+        prepared = prepared_host(host)
+        groups = cache_match(prepared, *DNS_PATTERNS)
+        if groups
+          dns = groups['dns']
+          @mutex.synchronize { @cached_dns_groups[prepared] = dns } if dns
+          true
+        else
+          false
+        end
+      end
+
+      def rds_cluster_dns?(host)
+        dns = dns_group(prepared_host(host))
+        !dns.nil? && (dns.casecmp('cluster-').zero? || dns.casecmp('cluster-ro-').zero?)
+      end
+
+      def rds_custom_cluster_dns?(host)
+        dns = dns_group(prepared_host(host))
+        !dns.nil? && dns.downcase.start_with?('cluster-custom-')
+      end
+
+      def rds_instance?(host)
+        prepared = prepared_host(host)
+        dns_group(prepared).nil? && rds_dns?(prepared)
+      end
+
+      def rds_proxy_dns?(host)
+        dns = dns_group(prepared_host(host))
+        !dns.nil? && dns.downcase.start_with?('proxy-')
+      end
+
+      def rds_proxy_endpoint_dns?(host)
+        prepared = prepared_host(host)
+        return false if blank?(prepared)
+
+        groups = match_first(prepared, *PROXY_ENDPOINT_PATTERNS)
+        !groups.nil? && !groups['dns'].nil? && !groups['instance'].nil?
+      end
+
+      def writer_cluster_dns?(host)
+        dns = dns_group(prepared_host(host))
+        !dns.nil? && dns.casecmp('cluster-').zero?
+      end
+
+      def reader_cluster_dns?(host)
+        dns = dns_group(prepared_host(host))
+        !dns.nil? && dns.casecmp('cluster-ro-').zero?
+      end
+
+      def limitless_db_shard_group_dns?(host)
+        dns = dns_group(prepared_host(host))
+        !dns.nil? && dns.casecmp('shardgrp-').zero?
+      end
+
+      def global_db_writer_cluster_dns?(host)
+        dns = dns_group(prepared_host(host))
+        !dns.nil? && dns.casecmp('global-').zero?
+      end
+
+      def ip?(host)
+        ipv4?(host) || ipv6?(host)
+      end
+
+      def ipv4?(host)
+        !blank?(host) && IP_V4.match?(host)
+      end
+
+      def ipv6?(host)
+        !blank?(host) && (IP_V6.match?(host) || IP_V6_COMPRESSED.match?(host))
+      end
+
+      # Priority-ordered type checks; first match wins.
+      RDS_TYPE_CHECKS = [
+        [:ip?,                            RdsUrlType::IP_ADDRESS],
+        [:global_db_writer_cluster_dns?,  RdsUrlType::RDS_GLOBAL_WRITER_CLUSTER],
+        [:writer_cluster_dns?,            RdsUrlType::RDS_WRITER_CLUSTER],
+        [:reader_cluster_dns?,            RdsUrlType::RDS_READER_CLUSTER],
+        [:rds_custom_cluster_dns?,        RdsUrlType::RDS_CUSTOM_CLUSTER],
+        [:limitless_db_shard_group_dns?,  RdsUrlType::RDS_AURORA_LIMITLESS_DB_SHARD_GROUP],
+        [:rds_proxy_endpoint_dns?,        RdsUrlType::RDS_PROXY_ENDPOINT],
+        [:rds_proxy_dns?,                 RdsUrlType::RDS_PROXY],
+        [:rds_dns?,                       RdsUrlType::RDS_INSTANCE]
+      ].freeze
+
+      def identify_rds_type(host)
+        return RdsUrlType::OTHER if blank?(host)
+
+        @cached_url_types.compute_if_absent(host) { classify_rds_type(host) }
+      end
+
+      def classify_rds_type(host)
+        RDS_TYPE_CHECKS.each do |check, type|
+          return type if send(check, host)
+        end
+
+        RdsUrlType::OTHER
+      end
+
+      def rds_host_id(host)
+        prepared = prepared_host(host)
+        return nil if blank?(prepared)
+
+        groups = cache_match(prepared, *DNS_PATTERNS)
+        return nil unless groups
+
+        groups['dns'] ? groups['instance'] : nil
+      end
+
+      def rds_cluster_id(host)
+        prepared = prepared_host(host)
+        return nil if blank?(prepared)
+
+        groups = cache_match(prepared, *DNS_GROUP_PATTERNS)
+        return nil unless groups
+
+        groups['dns'] ? groups['instance'] : nil
+      end
+
+      def rds_instance_name(host)
+        prepared = prepared_host(host)
+        return nil if blank?(prepared)
+
+        groups = cache_match(prepared, *DNS_PATTERNS)
+        return nil unless groups
+
+        groups['dns'].nil? ? groups['instance'] : nil
+      end
+
+      def rds_instance_host_pattern(host)
+        prepared = prepared_host(host)
+        return '?' if blank?(prepared)
+
+        groups = cache_match(prepared, *DNS_PATTERNS)
+        domain = groups&.[]('domain')
+        domain ? "?.#{domain}" : '?'
+      end
+
+      def rds_region(host)
+        prepared = prepared_host(host)
+        return nil if blank?(prepared)
+
+        groups = cache_match(prepared, *DNS_PATTERNS)
+        region = groups&.[]('region')
+        return region if valid_region?(region)
+
+        elb_match = ELB_PATTERN.match(prepared)
+        elb_region = elb_match&.[]('region')
+        valid_region?(elb_region) ? elb_region : nil
+      end
+
+      # Whether the given value is a real AWS region known to this wrapper.
+      #
+      # Case-insensitive. Returns false for nil/blank and for typos or otherwise
+      # incorrect values (e.g. "us-esat-1").
+      #
+      # @param region [String, nil]
+      # @return [Boolean]
+      def valid_region?(region)
+        return false if blank?(region)
+
+        KNOWN_REGIONS.include?(region.downcase)
+      end
+
+      # Whether the host carries a region segment that was parsed out of the
+      # endpoint but is NOT a real AWS region (i.e. a likely typo such as
+      # "us-esat-1").
+      #
+      # @param host [String, nil]
+      # @return [Boolean] true only when a region was captured and is invalid
+      def region_typo?(host)
+        prepared = prepared_host(host)
+        return false if blank?(prepared)
+
+        # Aurora Global Database endpoints carry the literal "global" in the region
+        # slot (e.g. "<id>.global.rds.amazonaws.com"), must never be treated as a typo.
+        return false if AURORA_GLOBAL_WRITER_DNS_PATTERN.match?(prepared)
+
+        groups = cache_match(prepared, *DNS_PATTERNS)
+        captured = groups&.[]('region')
+        return false if captured.nil? || captured.empty?
+
+        !valid_region?(captured)
+      end
+
+      def same_region?(host1, host2)
+        return false if blank?(host1) || blank?(host2)
+
+        region1 = rds_region(host1)
+        region2 = rds_region(host2)
+        !region1.nil? && region1.casecmp(region2).zero?
+      end
+
+      def rds_cluster_host_url(host)
+        prepared = prepared_host(host)
+        return nil if blank?(prepared)
+
+        CLUSTER_PATTERNS.each do |pattern, prefix|
+          m = pattern.match(prepared)
+          next unless m
+
+          return "#{m[:instance]}.#{prefix}#{m[:domain]}"
+        end
+
+        nil
+      end
+
+      def dns_pattern_valid?(pattern)
+        return false if blank?(pattern)
+
+        pattern.count('?') == 1
+      end
+
+      def remove_port(host_and_port)
+        return host_and_port if blank?(host_and_port)
+
+        idx = host_and_port.index(':')
+        idx ? host_and_port[0...idx] : host_and_port
+      end
+
+      def green_instance?(host)
+        prepared = prepared_host(host)
+        !blank?(prepared) && BG_GREEN_HOST_PATTERN.match?(prepared)
+      end
+
+      def old_instance?(host)
+        prepared = prepared_host(host)
+        !blank?(prepared) && BG_OLD_HOST_PATTERN.match?(prepared)
+      end
+
+      def not_old_instance?(host)
+        prepared = prepared_host(host)
+        blank?(prepared) || !BG_OLD_HOST_PATTERN.match?(prepared)
+      end
+
+      def not_green_and_old_prefix_instance?(host)
+        prepared = prepared_host(host)
+        !blank?(prepared) &&
+          !BG_GREEN_HOST_PATTERN.match?(prepared) &&
+          !BG_OLD_HOST_PATTERN.match?(prepared)
+      end
+
+      def remove_green_instance_prefix(host)
+        return nil if host.nil?
+        return host if host.empty?
+
+        prepared = prepared_host(host)
+        m = BG_GREEN_HOST_PATTERN.match(prepared)
+        unless m
+          hostid_m = BG_GREEN_HOSTID_PATTERN.match(prepared)
+          return hostid_m ? hostid_m[1] : host
+        end
+
+        prefix = m[:prefix]
+        return host if blank?(prefix)
+
+        host.sub("#{prefix}.", '.')
+      end
+
+      private
+
+      def blank?(str)
+        str.nil? || str.empty?
+      end
+
+      def prepared_host(host)
+        return host unless @prepare_host_func
+
+        result = @prepare_host_func.call(host)
+        result || host
+      end
+
+      def cache_match(host, *patterns)
+        # Only non-nil match groups are stored, so a nil lookup means "not cached".
+        cached = @cached_matches[host]
+        return cached if cached
+
+        patterns.each do |pattern|
+          m = pattern.match(host)
+          next unless m
+
+          groups = m.named_captures
+          @cached_matches[host] = groups
+          return groups
+        end
+
+        nil
+      end
+
+      def dns_group(host)
+        return nil if blank?(host)
+
+        @mutex.synchronize { return @cached_dns_groups[host] if @cached_dns_groups.key?(host) }
+
+        groups = cache_match(host, *DNS_GROUP_PATTERNS)
+        dns = groups&.[]('dns')
+        @mutex.synchronize { @cached_dns_groups[host] = dns }
+        dns
+      end
+
+      def match_first(host, *patterns)
+        patterns.each do |pattern|
+          m = pattern.match(host)
+          return m.named_captures if m
+        end
+        nil
+      end
+    end
+  end
+end