flare 0.4.2 → 0.5.0

data/lib/flare/metric_span_processor.rb

@@ -2,6 +2,8 @@
 
 require_relative "metric_key"
 require_relative "http_metrics_config"
+require_relative "sql_mask"
+require_relative "store_statement"
 
 module Flare
   TRANSACTION_NAME_ATTRIBUTE = "flare.transaction_name" unless const_defined?(:TRANSACTION_NAME_ATTRIBUTE)
@@ -9,6 +11,8 @@ module Flare
   # OpenTelemetry SpanProcessor that extracts metrics from spans.
   # Aggregates counts, durations, and error rates by namespace/service/target/operation.
   class MetricSpanProcessor
+    MAX_METRIC_STATEMENT_BYTES = 4_096
+
     # Standard OTel span kind symbols
     SERVER = :server
     CLIENT = :client
@@ -55,6 +59,14 @@ module Flare
       elsif view_span?(span)
         record_view_metric(span)
       end
+    rescue StandardError => e
+      # The SDK calls processors without a rescue, so a bug here would raise
+      # into the app's request or job. Warn once per process so it can't
+      # flood the logs (keyed by pid so forked workers still warn).
+      return if @on_finish_error_warned_pid == $$
+
+      @on_finish_error_warned_pid = $$
+      warn "[Flare::MetricSpanProcessor] on_finish failed: #{e.class}: #{e.message}"
     end
 
     def force_flush(timeout: nil)
@@ -169,13 +181,21 @@ module Flare
 
     def record_db_metric(span)
       db_system = span.attributes["db.system"].to_s
+      # Read the table and operation from the statement without its values, so
+      # the words in a string literal can't become the metric's name. This runs on
+      # the request thread and needs only the start of a statement, and a literal
+      # the cut lands in is masked like any unterminated one.
+      raw_statement = span.attributes["db.statement"]
+      if raw_statement && SqlMask.sql_system?(db_system)
+        statement = SqlMask.mask(raw_statement.to_s.byteslice(0, MAX_METRIC_STATEMENT_BYTES), db_system)
+      end
 
       key = MetricKey.new(
         bucket: bucket_time(span),
         namespace: "db",
         service: db_system,
-        target: extract_db_target(span, db_system),
-        operation: extract_db_operation(span, db_system)
+        target: extract_db_target(span, db_system, statement),
+        operation: extract_db_operation(span, db_system, statement)
       )
 
       @storage.increment(
@@ -191,17 +211,18 @@ module Flare
              span.attributes["net.peer.name"] ||
              extract_host_from_url(span) ||
              "unknown"
+      host = host.to_s.sub(/\A.*@/m, "").downcase
 
       method = span.attributes["http.method"] ||
                span.attributes["http.request.method"] ||
                "UNKNOWN"
 
-      path = resolve_http_path(span, host.to_s.downcase)
+      path = resolve_http_path(span, host)
 
       key = MetricKey.new(
         bucket: bucket_time(span),
         namespace: "http",
-        service: host.to_s.downcase,
+        service: host,
         target: "#{method.to_s.upcase} #{path}",
         operation: http_status_class(span)
       )
@@ -257,9 +278,14 @@ module Flare
       ((span.end_timestamp - span.start_timestamp) / 1_000_000.0).round
     end
 
+    # A 5xx is an error. So is a request that raised before any response
+    # (a timeout, a dropped connection): it has no status code, only an error
+    # span status. 4xx responses also carry an error span status, so the
+    # span status only counts when there was no response at all.
     def http_error?(span)
       status = span.attributes["http.status_code"] || span.attributes["http.response.status_code"]
-      status.to_i >= 500
+      code = status.to_i
+      code >= 500 || (code.zero? && span_error?(span))
     end
 
     def http_status_class(span)
@@ -291,50 +317,40 @@ module Flare
       end
     end
 
-    def extract_db_target(span, db_system)
-      case db_system
-      when "redis"
+    def extract_db_target(span, db_system, statement)
+      if StoreStatement.redis_system?(db_system)
         # For Redis, use db.redis.namespace if available, or the database index
         span.attributes["db.redis.database_index"]&.to_s ||
           span.attributes["db.name"] ||
           "default"
       else
-        # For SQL databases, prefer table name from attributes or parsed from SQL
+        # Prefer the table name from attributes. Only SQL statements are parsed
+        # for one; statement is nil for anything else.
         span.attributes["db.sql.table"] ||
-          extract_sql_table(span) ||
+          span.attributes["db.mongodb.collection"] ||
+          span.attributes["db.collection.name"] ||
+          extract_sql_table(statement) ||
           span.attributes["db.name"] ||
           "unknown"
       end
     end
 
-    def extract_db_operation(span, db_system)
-      case db_system
-      when "redis"
-        span.attributes["db.operation"]&.to_s&.downcase ||
-          span.name.to_s.split.last&.downcase ||
-          "command"
+    def extract_db_operation(span, db_system, statement)
+      operation = SqlMask.operation_word(span.attributes["db.operation"])
+
+      if StoreStatement.redis_system?(db_system)
+        (operation || SqlMask.operation_word(span.name.to_s.split.last))&.downcase || "query"
       else
-        span.attributes["db.operation"]&.to_s&.upcase ||
-          extract_sql_operation(span) ||
-          "query"
+        # The first word of a masked statement (SELECT, INSERT, UPDATE, etc.)
+        word = statement ? statement.split(" ", 2).first : SqlMask.command_word(span.attributes["db.statement"])
+        (operation || word)&.upcase || "query"
       end
     end
 
-    def extract_sql_operation(span)
-      statement = span.attributes["db.statement"]
+    def extract_sql_table(statement)
       return nil unless statement
 
-      # Extract first word (SELECT, INSERT, UPDATE, DELETE, etc.)
-      statement.to_s.strip.split(/\s+/).first&.upcase
-    end
-
-    def extract_sql_table(span)
-      statement = span.attributes["db.statement"]
-      return nil unless statement
-
-      sql = statement.to_s.strip
-
-      case sql
+      case statement
       when /\bFROM\s+[`"]?(\w+)[`"]?/i
         $1
       when /\bINTO\s+[`"]?(\w+)[`"]?/i
@@ -373,7 +389,7 @@ module Flare
       path = span.attributes["http.target"] ||
              span.attributes["url.path"] ||
              extract_path_from_url(span)
-      path&.to_s&.split("?")&.first || "/"
+      path&.to_s&.split(/[?#]/)&.first || "/"
     end
 
     # Normalize URL paths to prevent cardinality explosion.
@@ -395,8 +411,8 @@ module Flare
         when /\A[0-9a-f]{24}\z/i
           # MongoDB ObjectId: /items/507f1f77bcf86cd799439011 -> /items/:id
           ":id"
-        when /\A[0-9a-f]{32,}\z/i
-          # Long hex strings (tokens, hashes): -> :token
+        when /\A[0-9a-f]{32,}\z/i, /[^@]@/
+          # Long hex strings (tokens, hashes), or anything shaped like user@host: -> :token
           ":token"
         else
           segment

data/lib/flare/metric_submitter.rb

@@ -24,6 +24,14 @@ module Flare
     # Max retries before giving up
     MAX_RETRIES = 3
 
+    # Network errors worth another try. A DNS failure or an unreachable host
+    # fails before anything is sent, like a refused connection.
+    RETRIABLE_ERRORS = [
+      Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+      Errno::ECONNREFUSED, Errno::ECONNRESET,
+      SocketError, Errno::EHOSTUNREACH, Errno::ENETUNREACH
+    ].freeze
+
     class SubmissionError < StandardError
       attr_reader :request_id, :response_code, :response_body
 
@@ -179,7 +187,7 @@ module Flare
           result, should_retry = yield
           return [nil, DeadlineExceeded.new("metric submission deadline exceeded")] if deadline.expired?
           return [result, nil] unless should_retry
-        rescue SubmissionError, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        rescue SubmissionError, *RETRIABLE_ERRORS => e
           last_error = e
           attempts_remaining -= 1
 

data/lib/flare/recording_batch_span_processor.rb

@@ -35,6 +35,8 @@ module Flare
       detect_forking
 
       @mutex.synchronize do
+        return if @stopped
+
         overflow = @queue.length + 1 - @max_queue_size
         @queue.shift(overflow) if overflow.positive?
         @queue << span
@@ -160,7 +162,13 @@ module Flare
       end
       SUCCESS
     ensure
-      @mutex.synchronize { @queue.unshift(*snapshot) } if snapshot&.any?
+      if snapshot&.any?
+        @mutex.synchronize do
+          @queue.unshift(*snapshot)
+          overflow = @queue.length - @max_queue_size
+          @queue.shift(overflow) if overflow.positive?
+        end
+      end
     end
 
     def start_flush_export(snapshot, deadline)

data/lib/flare/redis_statement_processor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+
+require_relative "store_statement"
+
+module Flare
+  # Replaces a Redis statement with its shape as the span starts, so raw arguments
+  # never reach a finished span: not the development database, not an export, and
+  # not another exporter the app has added. The Redis instrumentation sends the
+  # key only when it's told to include arguments, which Flare does for this.
+  class RedisStatementProcessor < OpenTelemetry::SDK::Trace::SpanProcessor
+    STATEMENT = "db.statement"
+
+    def on_start(span, _parent_context)
+      return unless span.kind == :client
+
+      attributes = span.attributes
+      return unless attributes && StoreStatement.redis_system?(attributes["db.system"])
+
+      statement = attributes[STATEMENT]
+      return unless statement
+
+      span.set_attribute(STATEMENT, StoreStatement.redis(statement, pipelined: span.name == "PIPELINED"))
+    rescue StandardError
+      span.set_attribute(STATEMENT, StoreStatement::PLACEHOLDER) if span.respond_to?(:set_attribute)
+    end
+  end
+end

data/lib/flare/revision.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Flare
+  # Works out the deployed revision of the app this client runs in, usually a
+  # git SHA. Flare.configuration.revision calls it once, the first time the
+  # revision is asked for; it's sent as X-Client-Revision so the server can
+  # mark deploys on the charts.
+  #
+  # In order:
+  #   1. The configured value (config.revision, which defaults to FLARE_REVISION)
+  #   2. A platform's variable (Heroku, Render, Railway, Kamal, Fly, ...)
+  #   3. A REVISION file in the app root (Capistrano, many Docker builds)
+  #   4. git rev-parse HEAD, only when the app root has a .git directory
+  # Nil when none of them answer; the server treats a missing header as
+  # "unknown".
+  module Revision
+    MAX_LENGTH = 64
+
+    # Variable => how to read a revision from it (nil: the value as is).
+    PLATFORM_VARIABLES = {
+      "HEROKU_SLUG_COMMIT" => nil,
+      "RENDER_GIT_COMMIT" => nil,
+      "RAILWAY_GIT_COMMIT_SHA" => nil,
+      "KAMAL_VERSION" => nil,
+      # The whole image reference ("registry.fly.io/app:deployment-01J...@sha256:...").
+      # Its tag names the deploy, and is the git SHA when deployed with --image-label.
+      "FLY_IMAGE_REF" => ->(ref) { ref.split("@", 2).first.to_s[%r{:([^:/]+)\z}, 1] },
+      "GIT_SHA" => nil,
+      "SOURCE_VERSION" => nil
+    }.freeze
+
+    def self.resolve(configured, env: ENV, root: app_root)
+      revision = clean(configured) || platform_revision(env) ||
+        clean(revision_file(root)) || clean(git_head(root))
+      revision&.freeze
+    end
+
+    # The first platform variable that holds a revision. Stops there, so a
+    # later variable is never parsed.
+    def self.platform_revision(env)
+      PLATFORM_VARIABLES.each do |name, extract|
+        value = env[name]
+        value = clean(extract && value ? extract.call(value) : value)
+        return value if value
+      end
+      nil
+    end
+
+    # Up to the first line break (CR or LF), stripped and capped, since it
+    # goes in a header.
+    def self.clean(value)
+      value = value.to_s.strip.split(/[\r\n]/, 2).first.to_s.strip
+      return if value.empty?
+
+      value[0, MAX_LENGTH]
+    end
+
+    def self.app_root
+      if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+        ::Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    end
+
+    def self.revision_file(root)
+      path = File.join(root, "REVISION")
+      File.read(path, 256) if File.file?(path)
+    rescue StandardError
+      nil
+    end
+
+    def self.git_head(root)
+      return unless File.exist?(File.join(root, ".git"))
+
+      output = IO.popen(["git", "-C", root, "rev-parse", "HEAD"], err: File::NULL, &:read)
+      output if $?.success?
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/flare/source_location.rb

@@ -16,11 +16,13 @@ module Flare
       /lib\/active_support/,
       /lib\/action_/,
       /opentelemetry/,
-      /flare/,
       /<internal:/,
       /\/bin\//,
     ].freeze
 
+    # Frames from this gem itself (for path: and git: installs outside /gems/).
+    GEM_ROOT = "#{File.expand_path("../..", __dir__)}/"
+
     module_function
 
     # Find the first app source location from the current backtrace
@@ -39,36 +41,39 @@ module Flare
     # Find multiple app source locations from the current backtrace
     # Returns an array of cleaned backtrace lines (up to MAX_TRACE_LINES)
     def find_trace
-      backtrace = caller(2, 100)
-      return [] unless backtrace
-
-      # Filter to only app code lines
-      app_lines = backtrace.select { |line| app_code?(line) }
-      return [] if app_lines.empty?
-
-      # Clean and format each line, limit to MAX_TRACE_LINES
-      app_lines.first(MAX_TRACE_LINES).map { |line| clean_backtrace_line(line) }
+      app_lines(caller(2, 100)).map { |line| clean_backtrace_line(line) }
     end
 
-    # Add source location attributes to a hash (for span attributes)
+    # Add source location attributes to a hash (for span attributes).
+    # Captures the backtrace once for both the location and the trace.
     def add_to_attributes(attrs)
-      location = find
+      lines = app_lines(caller(1, 100))
+      location = lines.first && parse_backtrace_line(lines.first)
       return attrs unless location
 
       attrs["code.filepath"] = location[:filepath]
       attrs["code.lineno"] = location[:lineno]
       attrs["code.function"] = location[:function] if location[:function]
-
-      # Add full trace as a single string attribute
-      trace = find_trace
-      attrs["code.stacktrace"] = trace.join("\n") if trace.any?
+      attrs["code.stacktrace"] = lines.map { |line| clean_backtrace_line(line) }.join("\n")
 
       attrs
     end
 
+    # The first MAX_TRACE_LINES app code lines of a backtrace.
+    def app_lines(backtrace)
+      return [] unless backtrace
+
+      backtrace.select { |line| app_code?(line) }.first(MAX_TRACE_LINES)
+    end
+
     def app_code?(line)
       # Must contain /app/ (Rails convention) and not match ignore patterns
       return false unless line.include?("/app/")
+      return false if line.start_with?(GEM_ROOT)
+
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        return true if line.start_with?("#{Rails.root}/app/")
+      end
 
       IGNORE_PATTERNS.none? { |pattern| line.match?(pattern) }
     end

data/lib/flare/sql_mask.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Flare
+  # Takes the values out of a SQL statement in one left-to-right pass, keeping
+  # keywords and names so the same query with different values reads the same.
+  #
+  # The first delimiter decides the token, so a quote inside a comment or a
+  # comment marker inside a string can't change how the rest is read. When the
+  # scan can't tell where a value ends (an unterminated literal or comment, or a
+  # backslash before a quote, which means different things across databases and
+  # server settings), everything after that point is masked.
+  module SqlMask
+    PLACEHOLDER = "?"
+
+    # Longer statements are masked up to here and cut, which bounds the work.
+    MAX_BYTES = 16_384
+    TRUNCATED = " ..."
+
+    # Systems known to speak SQL. Anything else may not follow its quoting rules,
+    # so callers keep only a command word. No system at all is read as SQL, with
+    # every quote treated as a value.
+    SQL_SYSTEMS = /postgres|postgis|mysql|trilogy|maria|sqlite|cockroach|sqlserver|mssql|oracle|db2/i
+
+    # Close enough to SQL to mask, with rules that vary: every quoted string counts
+    # as a value, and # and // start comments that run to the end of the line.
+    # Backticks hold names only where that's known.
+    SQL_LIKE_SYSTEMS = /cassandra|clickhouse|bigquery|snowflake/i
+    BACKTICK_NAMES = /clickhouse|bigquery/i
+
+    # Double quotes hold names on these. On MySQL they hold values, and elsewhere
+    # they're treated as values too. SQLite reads them as values when no such
+    # column exists, so it keeps them only in places that can't hold a value.
+    # MySQL also starts comments with #, which is an operator on Postgres.
+    DOUBLE_QUOTED_NAMES = /postgres|postgis|cockroach|oracle|db2/i
+    SQLITE = /sqlite/i
+    HASH_COMMENTS = /mysql|trilogy|maria/i
+
+    COMMAND_WORD = /\A\s*([A-Z][A-Z_.]{0,31}|[a-z][a-z_.]{0,31})(?=\s|\z)/
+    OPERATION_WORD = /\A[A-Za-z][A-Za-z_.]{0,31}\z/
+    # Decided from a short tail of the output, so anything spaced too widely to see
+    # in it isn't a name. FROM counts only with the word before it in view, because
+    # IS DISTINCT FROM takes a value.
+    NAME_POSITION = /(?:\b(?:JOIN|INTO|UPDATE|TABLE)\s{1,8}|\.)\z/ni
+    FROM_POSITION = /(\S+)\s{1,8}FROM\s{1,8}\z/ni
+    DISTINCT_WORD = /DISTINCT\z/ni
+    DOUBLE_QUOTED = /"[^"]*+(?:""[^"]*+)*+"/n
+    QUALIFIER = /#{DOUBLE_QUOTED.source}(?=\.(?:\*|\w|#{DOUBLE_QUOTED.source}))/n
+
+    WORD = /[A-Za-z_\x80-\xff][\w$\x80-\xff]*+/n
+    UUID = /\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\b/n
+    NUMBER = /\.?\d[\w.\x80-\xff]*+(?:(?<=[eE])[+-]\d++)?/n
+    DOLLAR_OTHER = /\$\d*+/n
+    DOLLAR_TAG = /\$(?:[A-Za-z_\x80-\xff][\w\x80-\xff]*+)?\$/n
+    LINE_COMMENT = /(?:--|#|\/\/)[^\n]*+/n
+    COMMENT_START = %r{/\*}n
+    COMMENT_EDGE = %r{/\*|\*/}n
+    LITERAL_PREFIX = /\A(?:[xXbBnNeE]|_\w+)\z/n
+    LITERAL_RUNS = { "'" => /[^'\\]*+/n, '"' => /[^"\\]*+/n, "`" => /[^`\\]*+/n }.freeze
+    IN_LIST = /\bIN ?\( ?\?(?: ?, ?\?)* ?\)/ni
+    OTHER_WHITESPACE = "\t\n\r\f\v"
+
+    # A run of tokens that are copied as they are, matched in one go because most
+    # of a statement is this. It stops at anything that needs a decision: a quote,
+    # a number, a $, a comment, or a word that may be a literal's prefix.
+    # A word that starts a UUID stops the run, so the whole UUID can be masked.
+    word = %q{(?!\h{8}-\h{4}-)[A-Za-z_\x80-\xff][\w$\x80-\xff]*+(?!')}
+    other = %q{[^\w\x80-\xff'"`$#./-]++|\.(?!\d)|-(?!-)}
+    backtick = "`[^`]*+(?:``[^`]*+)*+`"
+    plain = "#{word}|#{other}|#{backtick}|/(?!\\*)"
+    PLAIN = Regexp.new("(?:#{plain})++", Regexp::NOENCODING)
+    PLAIN_NAMES = Regexp.new(%((?:#{plain}|#{DOUBLE_QUOTED.source}|#)++), Regexp::NOENCODING)
+    PLAIN_HASH = Regexp.new("(?:#{plain}|#)++", Regexp::NOENCODING)
+    PLAIN_LIKE = Regexp.new("(?:#{word}|#{other}|/(?![*/]))++", Regexp::NOENCODING)
+    PLAIN_LIKE_BACKTICKS = Regexp.new("(?:#{word}|#{other}|#{backtick}|/(?![*/]))++", Regexp::NOENCODING)
+
+    module_function
+
+    def sql_system?(system)
+      system.to_s.empty? || SQL_SYSTEMS.match?(system.to_s) || SQL_LIKE_SYSTEMS.match?(system.to_s)
+    end
+
+    # The first word of a statement, if it could be a command name. Nil otherwise.
+    def command_word(statement)
+      statement.to_s[COMMAND_WORD, 1]
+    end
+
+    # The value if all of it could be an operation name. Nil otherwise.
+    def operation_word(value)
+      value.to_s[OPERATION_WORD]
+    end
+
+    def mask(statement, system = nil)
+      sql = statement.to_s.b
+      truncated = sql.bytesize > MAX_BYTES
+      sql = sql.byteslice(0, MAX_BYTES) if truncated
+      out = scan(StringScanner.new(sql), system.to_s)
+      out.tr!(OTHER_WHITESPACE, " ")
+      out.squeeze!(" ")
+      out.gsub!(IN_LIST, "IN (?)")
+      out.strip!
+      out << TRUNCATED if truncated
+      out.force_encoding(Encoding::UTF_8).scrub!
+    end
+
+    def scan(scanner, system)
+      sqlite = SQLITE.match?(system)
+      plain = if SQL_LIKE_SYSTEMS.match?(system) then BACKTICK_NAMES.match?(system) ? PLAIN_LIKE_BACKTICKS : PLAIN_LIKE
+      elsif DOUBLE_QUOTED_NAMES.match?(system) then PLAIN_NAMES
+      elsif system.empty? || HASH_COMMENTS.match?(system) then PLAIN
+      else PLAIN_HASH
+      end
+      out = String.new(capacity: scanner.string.bytesize, encoding: Encoding::BINARY)
+
+      until scanner.eos?
+        if (run = scanner.scan(plain))
+          out << run
+        elsif scanner.skip(UUID) || scanner.skip(NUMBER)
+          out << PLACEHOLDER
+        elsif (word = scanner.scan(WORD))
+          if LITERAL_PREFIX.match?(word)
+            mask_literal(scanner, out, backslash_escapes: word.casecmp?("e"))
+          else
+            out << word
+          end
+        else
+          scan_delimiter(scanner, out, plain, sqlite)
+        end
+      end
+
+      out
+    end
+
+    # Handles the delimiter the plain run stopped on. Giving up on the rest of the
+    # statement means terminating the scanner, which ends the loop above.
+    def scan_delimiter(scanner, out, plain, sqlite)
+      case scanner.peek(1)
+      when "'"
+        mask_literal(scanner, out)
+      when '"'
+        # A closed name would already be part of the plain run where quotes are names.
+        if plain == PLAIN_NAMES then mask_rest(scanner, out)
+        elsif sqlite && (name = sqlite_name(scanner, out)) then out << name
+        else mask_literal(scanner, out)
+        end
+      when "`"
+        # Likewise, where backticks are names.
+        plain == PLAIN_LIKE ? mask_literal(scanner, out) : mask_rest(scanner, out)
+      when "$"
+        mask_dollar(scanner, out)
+      else # /* or, where they start a comment, //, -- and #
+        if scanner.check(COMMENT_START)
+          skip_comment(scanner, out)
+        else
+          scanner.skip(LINE_COMMENT)
+          out << " "
+        end
+      end
+    end
+
+    # A quoted word right after FROM and the like, or either side of a dot, can
+    # only be a name.
+    def sqlite_name(scanner, out)
+      tail = out.byteslice(-32, 32) || out
+      from = FROM_POSITION.match(tail)
+      if NAME_POSITION.match?(tail) || (from && !DISTINCT_WORD.match?(from[1]))
+        scanner.scan(DOUBLE_QUOTED)
+      else
+        scanner.scan(QUALIFIER)
+      end
+    end
+
+    def mask_rest(scanner, out)
+      out << PLACEHOLDER
+      scanner.terminate
+    end
+
+    # The scanner is on the opening quote. Reads to the closing one, or masks the
+    # rest if there isn't one.
+    #
+    # An even run of backslashes before a quote closes the literal whether or not
+    # the server treats backslash as an escape. An odd run only closes it if the
+    # server doesn't, and that depends on the database and its settings, so the
+    # literal counts as unterminated. Only E'' strings say for themselves.
+    def mask_literal(scanner, out, backslash_escapes: false)
+      quote = scanner.getch
+      plain = LITERAL_RUNS.fetch(quote)
+      out << PLACEHOLDER
+
+      loop do
+        scanner.skip(plain)
+        return scanner.terminate if scanner.eos?
+
+        if scanner.peek(1) == "\\"
+          if backslash_escapes
+            scanner.skip(/\\.?/mn)
+          else
+            run = scanner.skip(/\\+/n)
+            return scanner.terminate if run.odd? && scanner.peek(1) == quote
+          end
+        else
+          scanner.getch
+          return unless scanner.peek(1) == quote
+
+          scanner.getch
+        end
+      end
+    end
+
+    def mask_dollar(scanner, out)
+      out << PLACEHOLDER
+      if (tag = scanner.scan(DOLLAR_TAG))
+        scanner.terminate unless scanner.skip_until(Regexp.new(Regexp.escape(tag), Regexp::NOENCODING))
+      else
+        scanner.skip(DOLLAR_OTHER)
+      end
+    end
+
+    # Comments nest on Postgres. Reading them that way elsewhere can only mask
+    # more, never less.
+    def skip_comment(scanner, out)
+      scanner.skip(COMMENT_START)
+      depth = 1
+      while depth.positive?
+        return scanner.terminate unless scanner.skip_until(COMMENT_EDGE)
+
+        depth += scanner.matched == "/*" ? 1 : -1
+      end
+      out << " "
+    end
+
+    private_class_method :scan, :scan_delimiter, :sqlite_name, :mask_rest, :mask_literal, :mask_dollar, :skip_comment
+  end
+end