aws_advanced_ruby_driver_wrapper 1.0.0

data/lib/aws_advanced_ruby_driver_wrapper/utils/events/data_access_event.rb

@@ -0,0 +1,26 @@
+# 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
+    module Events
+      # Event indicating data was accessed. Batched delivery (not immediate).
+      DataAccessEvent = Data.define(:data_type, :key) do
+        def immediate_delivery? = false
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/events/monitor_reset_event.rb

@@ -0,0 +1,26 @@
+# 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
+    module Events
+      # Event signaling that monitors for a cluster should be reset. Immediate delivery.
+      MonitorResetEvent = Data.define(:cluster_id, :endpoints) do
+        def immediate_delivery? = true
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/global_aurora_topology_utils.rb

@@ -0,0 +1,185 @@
+# 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/host_role'
+require_relative 'rds_url_type'
+require_relative 'rds_utils'
+require_relative 'aurora_topology_utils'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    # Topology utilities specific to Global Aurora database clusters.
+    # Global Aurora clusters span multiple AWS regions, so topology queries return a region column
+    # and instance templates are keyed by region.
+    class GlobalAuroraTopologyUtils < AuroraTopologyUtils
+      # Query the database for topology information across global Aurora cluster regions.
+      #
+      # @param conn [Object] the connection to use to query the database.
+      # @param initial_host_info [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the HostInfo used to initially connect.
+      # @param instance_templates_by_region [Hash<String, AwsAdvancedRubyDriverWrapper::Host::HostInfo>]
+      #   a map of AWS region to instance template HostInfo for constructing hosts.
+      # @return [Array<AwsAdvancedRubyDriverWrapper::Host::HostInfo>, nil] a list of HostInfo objects or nil.
+      def query_global_topology(conn, initial_host_info, instance_templates_by_region)
+        results = @dialect.execute(conn, @dialect.topology_query)
+
+        if results.fields.empty?
+          # We expect at least 4 columns. Note that the server may return 0 columns if failover has occurred.
+          logger.debug('The topology query returned a result with 0 columns. ' \
+                       'This may occur if the topology query is executed when the server is failing over.')
+          return nil
+        end
+
+        verify_writer(build_global_hosts(results, initial_host_info, instance_templates_by_region))
+      rescue StandardError => e
+        raise "Invalid topology query: #{e.message}"
+      end
+
+      # Retrieves the AWS region for a given instance ID.
+      #
+      # @param instance_id [String] the database instance identifier.
+      # @param conn [Object] the database connection.
+      # @return [String, nil] the AWS region, or nil if it cannot be determined.
+      def query_region(instance_id, conn)
+        results = @dialect.execute_with_params(conn, @dialect.region_by_instance_id_query, [instance_id])
+        return nil if results.nil? || results.none?
+
+        row = results.first
+        region = row.values.first
+        region.nil? || region.to_s.empty? ? nil : region.to_s
+      end
+
+      # Parses a comma-separated instance templates string into a region-to-HostInfo map.
+      # Each comma-separated entry in the string can be one of the following formats:
+      #   - "host_pattern"
+      #   - "host_pattern:port"
+      #   - "[region]host_pattern"
+      #   - "[region]host_pattern:port"
+      #
+      # @param instance_templates_string [String] comma-separated list of instance template entries.
+      # @param host_validator [Proc] proc to validate each host pattern.
+      # @return [Hash<String, AwsAdvancedRubyDriverWrapper::Host::HostInfo>] map of region to instance template.
+      # @raise [AwsError] if the host or region in any of the template strings could not be parsed.
+      def parse_instance_templates(instance_templates_string, host_validator)
+        templates = {}
+
+        instance_templates_string.split(',').each do |entry|
+          entry = entry.strip
+          region, host_pattern, port = extract_region_host_and_port(entry)
+          raise Errors::AwsError, "Unable to parse region from '#{entry}'" if region.nil? || region.empty?
+          raise Errors::AwsError, "Unable to parse host from '#{entry}'" if host_pattern.nil? || host_pattern.empty?
+
+          # The region may be supplied explicitly in square brackets (e.g. "[us-east-1]..."), validate it.
+          unless RdsUtils.valid_region?(region)
+            raise Errors::AwsError, "Unknown or misspelled AWS region '#{region}' in instance template '#{entry}'"
+          end
+
+          host_validator.call(host_pattern)
+          url_type = RdsUtils.identify_rds_type(host_pattern)
+          # assign HostRole of READER if using the reader cluster URL, otherwise assume a HostRole of WRITER
+          role = url_type == RdsUrlType::RDS_READER_CLUSTER ? Host::HostRole::READER : Host::HostRole::WRITER
+          templates[region.downcase] = Host::HostInfo.new(id: '?', host: host_pattern, port:, role:)
+        end
+
+        logger.debug("Detected global database patterns: #{templates}")
+        templates
+      end
+
+      private
+
+      # Process global Aurora topology query results into a list of HostInfo objects.
+      # Each row in 'results' includes a region column used to select the appropriate instance template.
+      #
+      # @param results [Object] the query result set (enumerable of row hashes).
+      # @param initial_host_info [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the initial host info.
+      # @param instance_templates_by_region [Hash<String, AwsAdvancedRubyDriverWrapper::Host::HostInfo>]
+      #   map of region to instance template.
+      # @return [Array<AwsAdvancedRubyDriverWrapper::Host::HostInfo>, nil] the parsed hosts or nil on failure.
+      def build_global_hosts(results, initial_host_info, instance_templates_by_region)
+        hosts_map = {}
+
+        results.each do |row|
+          host = build_host_from_row(row, initial_host_info, instance_templates_by_region)
+          hosts_map[host.host] = host
+        rescue StandardError => e
+          logger.debug("Error processing topology query results: #{e.message}")
+          return nil
+        end
+
+        hosts_map.values
+      end
+
+      # Builds a HostInfo from a single global Aurora topology query result row.
+      #
+      # Expected columns: host_id, is_writer, instance_lag, aws_region.
+      #
+      # @param row [Hash] a single row from the topology query result.
+      # @param initial_host_info [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the initial host info.
+      # @param instance_templates_by_region [Hash<String, AwsAdvancedRubyDriverWrapper::Host::HostInfo>]
+      #   map of region to instance template.
+      # @return [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the constructed host info.
+      # @raise [AwsError] if no template is found for the row's region.
+      def build_host_from_row(row, initial_host_info, instance_templates_by_region)
+        instance_id = row_value(row, 'instance_id')
+        is_writer = to_boolean(row_value(row, 'is_writer'))
+        lag = to_float(row_value(row, 'instance_lag'))
+        aws_region = row_value(row, 'aws_region').to_s.downcase
+
+        weight = (lag.round * 100)
+
+        instance_template = instance_templates_by_region[aws_region]
+        raise Errors::AwsError, "Cannot find instance template for region '#{aws_region}'" if instance_template.nil?
+
+        build_host(instance_id, instance_id, is_writer, weight, Time.now, initial_host_info, instance_template)
+      end
+
+      # Extracts the region, host pattern, and port from an instance template string.
+      # The region may be prefixed in square brackets or inferred from the host pattern, for example:
+      # - "[us-west-1]?.custom-host:5432"
+      # - "?.xyz.us-west-1.rds.amazonaws.com:5432"
+      #
+      # @param entry [String] a single instance template entry.
+      # @return [Array(String, String, Integer)] region, host_pattern, and port.
+      def extract_region_host_and_port(entry)
+        if entry.start_with?('[')
+          closing = entry.index(']')
+          raise ArgumentError, "Invalid instance template format: '#{entry}'" if closing.nil?
+
+          region = entry[1...closing]
+          host_pattern, port = parse_host_and_port(entry[(closing + 1)..])
+        else
+          host_pattern, port = parse_host_and_port(entry)
+          region = RdsUtils.rds_region(host_pattern)
+        end
+
+        [region, host_pattern, port]
+      end
+
+      # Parses "host_pattern" or "host_pattern:port" and returns [host_pattern, port].
+      def parse_host_and_port(value)
+        # Split from the right to handle host patterns that might not contain a colon.
+        # Only treat the last segment as a port if it's purely numeric.
+        last_colon = value.rindex(':')
+        if last_colon && value[(last_colon + 1)..].match?(/\A\d+\z/)
+          host_pattern = value[0...last_colon]
+          port = value[(last_colon + 1)..].to_i
+          [host_pattern, port]
+        else
+          [value, Host::HostInfo::NO_PORT]
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/host_list_utils.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 Utils
+    module HostListUtils
+      def self.writer(hosts) = hosts&.find { |host_info| host_info.role == HostRole::WRITER }
+
+      def self.contains_url?(hosts, url) = hosts&.any? { |host_info| host_info.url == url } || false
+
+      def self.to_host_urls_s(hosts) = hosts&.map(&:url)&.join(',') || ''
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/iam_auth_utils.rb

@@ -0,0 +1,112 @@
+# 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 'uri'
+require_relative 'rds_utils'
+require_relative 'rds_url_type'
+require_relative '../property_definition'
+require_relative '../logging'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module IamAuthUtils
+      module_function
+
+      TokenEntry = Data.define(:token, :expires_at) do
+        # Redact the token so it is never exposed if an instance is logged,
+        # interpolated, or rendered in a backtrace.
+        def inspect
+          "#<data TokenEntry token=#{AwsAdvancedRubyDriverWrapper::REDACTED.inspect}, " \
+            "expires_at=#{expires_at.inspect}>"
+        end
+        alias_method :to_s, :inspect
+
+        # `pp` / PrettyPrint does not call #inspect; route them through the
+        # redacted representation so `pp entry` cannot leak the token.
+        def pretty_print(pp)
+          pp.text(inspect)
+        end
+      end
+
+      EXPIRY_BUFFER_SEC = 60
+
+      def parse_token_expiry(token)
+        URI.decode_www_form(URI.parse("https://#{token}").query)
+           .filter_map { |(key, value)| Integer(value, 10) if key.downcase == 'x-amz-expires' }
+           .first
+      rescue StandardError
+        nil
+      end
+
+      def build_token_entry(token, fallback_expiry_sec)
+        expires_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) +
+                     (parse_token_expiry(token) || fallback_expiry_sec) -
+                     EXPIRY_BUFFER_SEC
+        TokenEntry.new(token:, expires_at:)
+      end
+
+      def valid_entry?(entry)
+        entry.is_a?(TokenEntry) && Process.clock_gettime(Process::CLOCK_MONOTONIC) < entry.expires_at
+      end
+
+      def region_for(host:, props:, rds_type:, credentials_provider:, rds_client_func: nil)
+        explicit = PropertyDefinition::IAM_REGION.get(props)
+        return explicit if explicit && !explicit.empty?
+
+        return RdsUtils.rds_region(host) unless rds_type == RdsUrlType::RDS_GLOBAL_WRITER_CLUSTER
+
+        region_from_global_cluster(host, credentials_provider, rds_client: rds_client_func&.call)
+      end
+
+      def region_from_global_cluster(host, credentials_provider, rds_client: nil)
+        cluster_id = RdsUtils.rds_cluster_id(host)
+        client = rds_client || Aws::RDS::Client.new(credentials: credentials_provider)
+        arn = client.describe_global_clusters(global_cluster_identifier: cluster_id)
+                    .global_clusters
+                    .flat_map(&:global_cluster_members)
+                    .find(&:is_writer)
+                    &.db_cluster_arn
+        # The partition segment of an ARN varies across AWS partitions, so match any of them.
+        arn&.match(/\Aarn:aws(?:-[a-z]+)*:rds:(?<region>[^:]+)/)&.[](:region)
+      end
+
+      def generate_token(region:, hostname:, port:, user:, credentials_provider:)
+        Aws::RDS::AuthTokenGenerator
+          .new(credentials: credentials_provider)
+          .auth_token(region:, endpoint: "#{hostname}:#{port}", user_name: user)
+      end
+
+      def resolve_host(iam_host, host_info)
+        return iam_host if iam_host && !iam_host.empty?
+
+        host_info.host
+      end
+
+      def resolve_port(iam_default_port, host_info, dialect_default_port)
+        iam_port = iam_default_port.to_i
+        return iam_port if iam_port.positive?
+
+        return host_info.port.to_i if host_info.port_specified?
+
+        dialect_default_port
+      end
+
+      def cache_key(region, host, port, user, credentials_identity)
+        "#{region}:#{host}:#{port}:#{user}:#{credentials_identity}"
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/multi_az_topology_utils.rb

@@ -0,0 +1,117 @@
+# 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'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    # Topology utilities specific to Multi-AZ database clusters.
+    # In Multi-AZ clusters, the writer is identified via a separate query rather than
+    # from a column in the topology results.
+    class MultiAzTopologyUtils
+      include TopologyUtils
+
+      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.
+      # In Multi-AZ, when connected to a writer, the writer ID query returns no rows.
+      #
+      # @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)
+        # When connected to a writer, the result is empty; otherwise it contains a single row.
+        results.nil? || results.none?
+      end
+
+      # Process Multi-AZ topology query results into a list of HostInfo objects.
+      # First determines the writer ID, then parses each row using endpoint and id columns.
+      #
+      # @param conn [Object] the database connection.
+      # @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 = {}
+        writer_id = query_writer_id(conn)
+
+        results.each do |row|
+          host = build_host_from_row(row, initial_host_info, instance_template, writer_id)
+
+          # 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
+
+      # Determines the writer instance ID by querying the database.
+      # The writer ID query returns the writer ID when connected to a reader.
+      # When connected to a writer, the query returns no rows, so we fall back to
+      # getting the host ID of the current connection.
+      #
+      # @param conn [Object] the database connection.
+      # @return [String, nil] the writer instance ID, or nil if it cannot be determined.
+      def query_writer_id(conn)
+        results = @dialect.execute(conn, @dialect.writer_id_query)
+
+        if results&.any?
+          row = results.first
+          writer_id_column = @dialect.respond_to?(:writer_id_column_name) ? @dialect.writer_id_column_name : 'writer_id'
+          writer_id = row_value(row, writer_id_column)
+          return writer_id unless writer_id.nil? || writer_id.to_s.empty?
+        end
+
+        # The writer ID is only returned when connected to a reader.
+        # If the query does not return a value, we are connected to the writer.
+        instance_id, = @dialect.instance_identity(conn)
+        instance_id
+      rescue StandardError
+        nil
+      end
+
+      # Builds a HostInfo from a single Multi-AZ topology query result row.
+      # Expected columns: endpoint.
+      #
+      # @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.
+      # @param writer_id [String, nil] the writer instance ID.
+      # @return [AwsAdvancedRubyDriverWrapper::Host::HostInfo] the constructed host info.
+      def build_host_from_row(row, initial_host_info, instance_template, writer_id)
+        instance_id = row_value(row, 'instance_id')
+        endpoint = row_value(row, 'endpoint')
+        # Extract instance name from the endpoint (everything before the first dot).
+        instance_name = endpoint&.split('.')&.first
+        build_host(instance_id, instance_name, instance_id == writer_id, 0, Time.now, initial_host_info, instance_template)
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/parser/encryption_annotation_parser.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.
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Parser
+      module EncryptionAnnotationParser
+        # Both placeholder styles are accepted, so that the same annotation works for mysql2's
+        # positional +?+ and pg's numbered +$1+.
+        ANNOTATION_PATTERN = %r{/\*@encrypt:([\w.]+)\*/\s*(?:\?|\$(\d+))}
+        STRIP_PATTERN = %r{/\*@encrypt:[\w.]+\*/\s*}
+        # The quote characters a literal can be wrapped in. A backtick quotes an identifier rather than
+        # a value, but is included so a +?+ inside a backtick-quoted name is not miscounted either.
+        QUOTES = ["'", '"', '`'].freeze
+
+        module_function
+
+        # Returns a 1-based map of parameter index => "table.column" for each
+        # /*@encrypt:table.column*/ ? or /*@encrypt:table.column*/ $n placeholder.
+        # @param sql [String]
+        # @return [Hash{Integer => String}]
+        def parse_annotations(sql)
+          return {} unless sql.is_a?(String) && !sql.empty?
+
+          question_marks = unquoted_question_mark_positions(sql)
+
+          sql.to_enum(:scan, ANNOTATION_PATTERN)
+             .each_with_object({}) do |_, result|
+               match = Regexp.last_match
+               next unless match
+
+               # A numbered placeholder states its own position; a question mark is located by
+               # counting the question marks that precede it.
+               if match[2]
+                 result[match[2].to_i] = match[1]
+               else
+                 param_index = question_marks.index(match.end(0) - 1)
+                 result[param_index + 1] = match[1] if param_index
+               end
+             end
+        end
+
+        def strip_annotations(sql)
+          return sql unless sql.is_a?(String) && !sql.empty?
+
+          sql.gsub(STRIP_PATTERN, '')
+        end
+
+        def annotations?(sql)
+          return false unless sql.is_a?(String) && !sql.empty?
+
+          ANNOTATION_PATTERN.match?(sql)
+        end
+
+        # The character positions of every +?+ that is a bind placeholder, skipping any inside a quoted
+        # literal so a literal question mark does not shift the count of the placeholder an annotation
+        # points at. A doubled quote reads as one closing and one opening quote, and a backslash escapes
+        # the next character except inside a backtick, which matches how the drivers read a literal.
+        def unquoted_question_mark_positions(sql)
+          positions = []
+          quote = nil
+          index = 0
+
+          while index < sql.length
+            char = sql[index]
+            if quote
+              if char == '\\' && quote != '`'
+                index += 2
+                next
+              end
+
+              quote = nil if char == quote
+            elsif QUOTES.include?(char)
+              quote = char
+            elsif char == '?'
+              positions << index
+            end
+            index += 1
+          end
+
+          positions
+        end
+      end
+    end
+  end
+end