seo_geo 0.1.0

data/lib/seo_geo/robots.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module SeoGeo
+  # Builds robots.txt for one request host from {Configuration#host_policy} and {Configuration#crawlers}.
+  #
+  # RFC 9309 §2.2.1: a crawler obeys only the most specific group that names it and ignores +*+.
+  # So every named group carries the host's full rule list: allowed crawlers share the +*+ rule block
+  # (several +User-agent:+ lines, one block), denied crawlers get +Disallow: /+ plus {Configuration#allow_exceptions}
+  # and every host +disallow+, verbatim. Named groups do not inherit +*+, so a disallow more specific than an
+  # allow exception (+/.well-known/private+, or any encoding of it such as +/.%77ell-known/private+) must be
+  # repeated there; repeating all of them needs no prefix comparison that encodings could defeat.
+  # An +Allow: /+-only group is emitted only for tokens the app explicitly overrides to +:full_access+
+  # ({CrawlerOptions#override}); it re-opens host disallows to that bot by design. Closed hosts never get one.
+  #
+  # @example
+  #   SeoGeo::Robots.new(SeoGeo.config, "www.example.com").to_s
+  class Robots
+    # @param config [Configuration]
+    # @param host [String] request host
+    def initialize(config, host)
+      @config = config
+      @host = host
+      @policy = config.host_policy(host)
+    end
+
+    # @return [String] robots.txt body (ends with a newline)
+    def to_s
+      blocks = @policy.disallow_all? ? [closed_block] : open_blocks
+      trailer = [*sitemap_lines, *daum_lines]
+      text = blocks.map { |lines| lines.join("\n") }.join("\n\n")
+      text = "#{text}\n\n#{trailer.join("\n")}" unless trailer.empty?
+      "#{text}\n"
+    end
+
+    # @return [Array<String>] tokens sharing the +*+ rule block
+    def allowed_user_agents
+      managed_user_agents.select { |token| @config.crawlers.policy_for(token) == :allow }
+    end
+
+    # @return [Array<String>] tokens overridden to +:full_access+ (own group, +Allow: /+, host disallows ignored)
+    def full_access_user_agents
+      managed_user_agents.select { |token| @config.crawlers.policy_for(token) == :full_access }
+    end
+
+    # @return [Array<String>] tokens given +Disallow: /+
+    def denied_user_agents
+      managed_user_agents.select { |token| @config.crawlers.policy_for(token) == :deny }
+    end
+
+    private
+
+    # Undeclared host, +indexable: false+ host, or a non-indexable environment.
+    def closed_block
+      ["User-agent: *", *@policy.allow.map { |prefix| "Allow: #{prefix}" }, "Disallow: /"]
+    end
+
+    def open_blocks
+      blocks = [shared_block]
+      denied = denied_user_agents
+      unless denied.empty?
+        blocks << [*denied.map { |token| "User-agent: #{token}" },
+                   *@config.allow_exceptions.map { |prefix| "Allow: #{prefix}" }, "Disallow: /",
+                   *@policy.disallow.uniq.map { |prefix| "Disallow: #{prefix}" }]
+      end
+      full = full_access_user_agents
+      unless full.empty?
+        blocks << [*full.map { |token| "User-agent: #{token}" }, "Allow: /",
+                   *@config.allow_exceptions.map { |prefix| "Allow: #{prefix}" }]
+      end
+      blocks
+    end
+
+    def shared_block
+      lines = ["User-agent: *", *allowed_user_agents.map { |token| "User-agent: #{token}" }]
+      if @policy.disallow.empty?
+        lines << "Allow: /"
+      else
+        lines.concat(@policy.allow.map { |prefix| "Allow: #{prefix}" })
+        lines.concat(@policy.disallow.map { |prefix| "Disallow: #{prefix}" })
+      end
+      lines << "Content-Signal: #{@config.content_signal_value}"
+      usage = @config.content_usage_value
+      lines << "Content-Usage: #{usage}" if usage
+      lines
+    end
+
+    def managed_user_agents
+      tokens = Crawlers::PURPOSES.flat_map { |purpose| @config.crawlers.user_agents(purpose) }
+      (tokens + @config.crawlers.overrides.keys).uniq { |token| token.downcase }
+    end
+
+    def sitemap_lines
+      return [] unless @policy.sitemap
+
+      ["Sitemap: #{@config.origin_for(@host)}/sitemap.xml"]
+    end
+
+    def daum_lines
+      pin = @config.verification.daum_pin
+      return [] if pin.nil? || pin.to_s.empty? || @policy.disallow_all?
+
+      ["#DaumWebMasterTool:#{pin}"]
+    end
+  end
+end

data/lib/seo_geo/robots_directives.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "set"
+require "nokogiri"
+
+module SeoGeo
+  # Robots directives of one response, from every +<meta name="robots">+, every crawler-specific meta
+  # (+<meta name="googlebot">+) and every +X-Robots-Tag+ header, kept apart by scope:
+  # +global+ applies to every crawler, +scoped["googlebot"]+ only to that one. A crawler obeys the union of
+  # +global+ and its own scope, so a scoped directive never stands in for a global one.
+  #
+  # Shared by the Markdown response (copies the HTML's directives into +X-Robots-Tag+) and the audit
+  # (is a sitemap page noindex?).
+  #
+  # @example
+  #   directives = SeoGeo::RobotsDirectives.from_html(html).merge(SeoGeo::RobotsDirectives.parse_header(value))
+  #   directives.noindex?              # global noindex
+  #   directives.noindex?("googlebot") # global or googlebot-scoped
+  #   directives.to_header             # "noindex, googlebot: nofollow"
+  class RobotsDirectives
+    # Directives that carry a value after a colon; any other +name: rest+ token in a header names a crawler.
+    VALUE_DIRECTIVES = %w[max-snippet max-image-preview max-video-preview unavailable_after].freeze
+    # Meta names that address one crawler (besides the crawler table's tokens).
+    CRAWLER_META_NAMES = %w[googlebot googlebot-news googlebot-image bingbot msnbot slurp yandex yeti naverbot
+                            daumoa baiduspider duckduckbot applebot].freeze
+    PERMISSIVE = %w[index follow all].freeze
+
+    # @return [Set<String>]
+    attr_reader :global
+    # @return [Hash{String => Set<String>}] crawler token (lower case) => directives
+    attr_reader :scoped
+
+    # @param html [String, Nokogiri::HTML::Document]
+    # @return [RobotsDirectives]
+    def self.from_html(html)
+      doc = html.is_a?(Nokogiri::XML::Node) ? html : Nokogiri::HTML(html.to_s)
+      new.tap do |directives|
+        doc.css("meta[name]").each do |node|
+          name = node["name"].to_s.strip.downcase
+          if name == "robots"
+            directives.add(nil, node["content"])
+          elsif crawler_name?(name)
+            directives.add(name, node["content"])
+          end
+        end
+      end
+    end
+
+    # @param value [String, Array<String>, nil] one or several +X-Robots-Tag+ values (Rack joins repeated
+    #   headers with "\n"). Within one value, +bot: ...+ scopes the following directives to +bot+.
+    # @return [RobotsDirectives]
+    def self.parse_header(value)
+      new.tap do |directives|
+        Array(value).flat_map { |item| item.to_s.split("\n") }.each do |line|
+          scope = nil
+          tokens(line).each do |token|
+
+            name, rest = token.split(":", 2).map(&:strip)
+            if rest && !VALUE_DIRECTIVES.include?(name.downcase)
+              scope = name.downcase
+              token = rest
+            end
+            directives.add(scope, token)
+          end
+        end
+      end
+    end
+
+    # A date-valued +unavailable_after+ may contain a comma (RFC 850/1123: +Wed, 03 Dec 2025 13:09:53 GMT+). The
+    # piece after +unavailable_after: <weekday>+ belongs to that directive, not to a new one.
+    DATE_HEAD = /(?:\A|:)\s*unavailable_after\s*:\s*[A-Za-z]+\s*\z/i
+
+    # Splits a comma-separated directive list, keeping date commas inside +unavailable_after+.
+    # @param content [String, nil]
+    # @return [Array<String>] stripped, non-empty tokens
+    def self.tokens(content)
+      content.to_s.split(",").each_with_object([]) do |piece, list|
+        if list.last&.match?(DATE_HEAD)
+          list[-1] = "#{list.last},#{piece.rstrip}"
+        else
+          list << piece.strip
+        end
+      end.reject(&:empty?)
+    end
+
+    # @param name [String] lower-case meta name
+    # @return [Boolean]
+    def self.crawler_name?(name)
+      CRAWLER_META_NAMES.include?(name) || Crawlers::ALL.any? { |crawler| crawler.user_agent.casecmp?(name) }
+    end
+
+    def initialize
+      @global = Set.new
+      @scoped = {}
+    end
+
+    # @param scope [String, nil] crawler token; nil => every crawler
+    # @param content [String, nil] comma-separated directives
+    # @return [self]
+    def add(scope, content)
+      target = scope ? (@scoped[scope.downcase] ||= Set.new) : @global
+      self.class.tokens(content).each do |raw|
+        directive = canonical(raw)
+        next if directive.empty?
+
+        directive == "none" ? target.merge(%w[noindex nofollow]) : target << directive
+      end
+      @scoped.delete(scope.downcase) if scope && target.empty?
+      self
+    end
+
+    # @param other [RobotsDirectives]
+    # @return [RobotsDirectives] a new object with both sets of directives; nothing is dropped
+    def merge(other)
+      self.class.new.tap do |result|
+        result.global.merge(global).merge(other.global)
+        [scoped, other.scoped].each do |source|
+          source.each { |bot, set| (result.scoped[bot] ||= Set.new).merge(set) }
+        end
+      end
+    end
+
+    # @return [RobotsDirectives] copy without +index+/+follow+/+all+ (they restrict nothing)
+    def restrictive
+      self.class.new.tap do |result|
+        result.global.merge(global - PERMISSIVE)
+        scoped.each do |bot, set|
+          rest = set - PERMISSIVE
+          result.scoped[bot] = rest unless rest.empty?
+        end
+      end
+    end
+
+    # @param bot [String, nil] crawler token; nil => global directives only
+    # @return [Boolean]
+    def noindex?(bot = nil)
+      global.include?("noindex") || (!bot.nil? && scoped.fetch(bot.downcase, Set.new).include?("noindex"))
+    end
+
+    # @return [Boolean] true when any crawler is told noindex (globally or in its own scope)
+    def noindex_for_any?
+      global.include?("noindex") || scoped.each_value.any? { |set| set.include?("noindex") }
+    end
+
+    # @return [Boolean]
+    def empty?
+      global.empty? && scoped.empty?
+    end
+
+    # @return [String] one +X-Robots-Tag+ value: global directives first (a scope runs to the end of the value,
+    #   so unscoped ones must precede every +bot:+), then each crawler's
+    def to_header
+      parts = global.to_a
+      scoped.each { |bot, set| parts << "#{bot}: #{set.to_a.join(", ")}" unless set.empty? }
+      parts.join(", ")
+    end
+
+    def ==(other)
+      other.is_a?(RobotsDirectives) && global == other.global && scoped == other.scoped
+    end
+
+    private
+
+    # Lower-cases the directive name; a value after +:+ keeps its case (+unavailable_after: 25 Jun 2026+).
+    def canonical(raw)
+      name, value = raw.strip.split(":", 2)
+      value.nil? ? name.to_s.downcase : "#{name.downcase}:#{value}"
+    end
+  end
+end

data/lib/seo_geo/robots_path.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module SeoGeo
+  # The one path normalization seo_geo uses wherever a path is compared with a robots rule or a
+  # declaration: robots.txt evaluation, {Publication}, {PathMatch} (noindex declarations, sitemap
+  # exclusions), llms.txt link filtering and the robots.txt denied groups.
+  #
+  # RFC 9309 §2.2.2 (with RFC 3986 §6.2.2): rules and paths are compared in percent-encoded form.
+  # - Escapes of unreserved characters are decoded (+/%61dmin+ == +/admin+).
+  # - Escapes of +$+ and +*+ are decoded too (RFC 9309 §2.2.3: +/foo-%24+ matches the path +/foo-$+); the robots
+  #   pattern compiler splits wildcards/anchors before normalizing, so they stay literals there.
+  # - Every other escape stays encoded, upper-cased: +%2F+, +%3F+, +%23+... are not +/+, +?+, +#+.
+  # - Non-ASCII bytes, controls and spaces are percent-encoded (UTF-8 octets, upper case).
+  module RobotsPath
+    UNRESERVED = /[A-Za-z0-9\-._~]/
+    DECODED_LITERALS = %w[$ *].freeze
+    private_constant :UNRESERVED, :DECODED_LITERALS
+
+    module_function
+
+    # @param value [String] a path, path pattern piece or request target (query kept)
+    # @return [String] normalized ASCII
+    def normalize(value)
+      out = +""
+      bytes = value.to_s.b
+      index = 0
+      while index < bytes.bytesize
+        byte = bytes.getbyte(index)
+        if byte == 0x25 && bytes[index + 1, 2].to_s.match?(/\A\h\h\z/)
+          char = bytes[index + 1, 2].hex.chr
+          out << (char.match?(UNRESERVED) || DECODED_LITERALS.include?(char) ? char : "%#{bytes[index + 1, 2].upcase}")
+          index += 3
+          next
+        end
+        out << (byte == 0x25 || byte <= 0x20 || byte >= 0x7F ? format("%%%02X", byte) : byte.chr)
+        index += 1
+      end
+      out
+    end
+
+    # Request target of a path or absolute URL: scheme/authority and fragment removed, query kept, normalized.
+    # This is what robots.txt rules are matched against.
+    # @param value [String]
+    # @return [String]
+    def target(value)
+      raw = value.to_s.sub(%r{\A[a-z][a-z0-9+.\-]*://[^/?#]*}i, "").sub(/#.*\z/m, "")
+      raw = "/#{raw}" unless raw.start_with?("/")
+      normalize(raw)
+    end
+
+    # Path of a path or absolute URL: like {.target} with the query dropped (+""+ => +"/"+). Declarations
+    # ({Configuration#noindex_paths}, sitemap exclusions, +add path, index:/noindex:+) compare this.
+    # @param value [String]
+    # @return [String]
+    def path(value)
+      target(value).sub(/\?.*\z/m, "")
+    end
+
+    # The HTML page a published URL stands for: {.path}, then a +.md+ suffix mapped back through
+    # {Markdown::PathSuffix.html_path} (+/secret.md?x=1+ => +/secret+, +/index.md+ => +/+). The query is
+    # dropped before the suffix is looked at, so a query cannot hide it.
+    # @param value [String]
+    # @param markdown [Boolean] whether +.md+ URLs are served ({MarkdownOptions#enabled})
+    # @return [String]
+    def html_path(value, markdown: true)
+      plain = path(value)
+      markdown && plain.end_with?(".md") ? Markdown::PathSuffix.html_path(plain) : plain
+    end
+
+    # {.html_path} with the query kept: what robots rules see for a published URL (+/x.md?preview=1+ =>
+    # +/x?preview=1+), so a query-specific +Disallow: /x?preview=1+ still applies. Declarations ignore the query
+    # anyway ({.path}).
+    # @param value [String]
+    # @param markdown [Boolean]
+    # @return [String]
+    def html_target(value, markdown: true)
+      query = target(value)[/\?.*\z/m]
+      "#{html_path(value, markdown: markdown)}#{query}"
+    end
+
+    # Fully percent-decoded form (UTF-8) of {.path}, for user Regexps written against readable paths
+    # (+%r{\A/가이드}+); nil when the bytes are not valid UTF-8.
+    # @param value [String]
+    # @return [String, nil]
+    def decoded(value)
+      text = path(value).gsub(/(?:%\h\h)+/) { |chunk| [chunk.delete("%")].pack("H*") }.force_encoding(Encoding::UTF_8)
+      text.valid_encoding? ? text : nil
+    end
+
+    # Compiles one robots.txt path pattern: a raw +*+ is a wildcard, a raw trailing +$+ an end anchor, escaped
+    # ones (+%2A+, +%24+) are literals.
+    # @param pattern [String]
+    # @return [Array(Regexp, Integer)] matcher over {.normalize}d targets and the length used for precedence
+    def compile(pattern)
+      anchored = pattern.end_with?("$")
+      body = anchored ? pattern[0...-1] : pattern
+      literals = body.split("*", -1).map { |part| normalize(part) }
+      regex = Regexp.new("\\A#{literals.map { |part| Regexp.escape(part) }.join(".*")}#{anchored ? "\\z" : ""}")
+      [regex, literals.join("*").length + (anchored ? 1 : 0)]
+    end
+
+    # RFC 9309 §2.2.2 rule choice: the longest matching pattern wins, +Allow+ wins a tie, empty patterns are
+    # ignored.
+    # @param rules [Array<Array(Symbol, String)>] +[:allow | :disallow, pattern]+
+    # @param value [String] path or URL ({.target} is applied)
+    # @return [Array(Symbol, String), nil] the deciding rule, nil when none matches
+    def decide(rules, value)
+      candidate = target(value)
+      rules.reject { |_, pattern| pattern.to_s.empty? }
+           .map { |kind, pattern| [kind, pattern, compile(pattern)] }
+           .select { |_, _, (regex, _)| regex.match?(candidate) }
+           .max_by { |kind, _, (_, length)| [length, kind == :allow ? 1 : 0] }
+           &.first(2)
+    end
+
+    # @param allow [Array<String>]
+    # @param disallow [Array<String>]
+    # @param value [String]
+    # @return [Boolean] true when the rules disallow +value+
+    def blocked?(allow, disallow, value)
+      rule = decide(allow.map { |pattern| [:allow, pattern] } + disallow.map { |pattern| [:disallow, pattern] }, value)
+      !rule.nil? && rule.first == :disallow
+    end
+  end
+end

data/lib/seo_geo/rspec.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "seo_geo"
+require_relative "testing/environment"
+
+module SeoGeo
+  # RSpec matchers. Plain matcher objects — seo_geo does not depend on rspec; when RSpec is
+  # loaded, requiring this file includes the matchers into request specs.
+  #
+  # Each matcher accepts a response (anything with +#body+) or a String body.
+  #
+  # @example spec/requests/seo_spec.rb
+  #   require "seo_geo/rspec"
+  #
+  #   it "folds the alias host" do
+  #     host! "example.com"
+  #     get "/pricing"
+  #     expect(response).to have_seo_geo_canonical("https://www.example.com/pricing")
+  #     expect(response).to have_seo_geo_single_title
+  #   end
+  #
+  #   it "keeps the FAQ honest" do
+  #     get "/"
+  #     expect(response).to have_seo_geo_faq_matching_visible_text
+  #   end
+  #
+  #   it "serves a valid sitemap" do
+  #     get "/sitemap.xml"
+  #     expect(response).to be_seo_geo_valid_sitemap(origin: "https://www.example.com")
+  #   end
+  #
+  #   it "serves production robots" do
+  #     with_seo_geo_environment("production") { get "/robots.txt" }
+  #   end
+  #
+  #   it "keeps bots out of /admin" do
+  #     get "/robots.txt"
+  #     expect(response).not_to seo_geo_robots_allow("GPTBot", "/admin")
+  #   end
+  module RSpec
+    # Base for the matchers below.
+    class Matcher
+      attr_reader :problems
+
+      def initialize
+        @problems = []
+      end
+
+      # @param actual [#body, String]
+      # @return [Boolean]
+      def matches?(actual)
+        @problems = check(actual.respond_to?(:body) ? actual.body.to_s : actual.to_s)
+        @problems.empty?
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message
+        "expected #{description}, but: #{problems.join("; ")}"
+      end
+
+      def failure_message_when_negated
+        "expected not #{description}"
+      end
+    end
+
+    # +<link rel="canonical">+ equals the expected URL.
+    class CanonicalMatcher < Matcher
+      def initialize(expected)
+        super()
+        @expected = expected
+      end
+
+      def description
+        "canonical #{@expected}"
+      end
+
+      private
+
+      def check(body)
+        actual = Audit::HtmlDocument.new(body).canonical
+        actual == @expected ? [] : ["canonical was #{actual.inspect}"]
+      end
+    end
+
+    # Exactly one +<title>+.
+    class SingleTitleMatcher < Matcher
+      def description
+        "exactly one <title>"
+      end
+
+      private
+
+      def check(body)
+        Audit::Checks.title_count(Audit::HtmlDocument.new(body))
+      end
+    end
+
+    # FAQPage JSON-LD exists and every question/answer is in the visible text.
+    class FaqMatcher < Matcher
+      def description
+        "FAQPage JSON-LD matching the visible FAQ"
+      end
+
+      private
+
+      def check(body)
+        doc = Audit::HtmlDocument.new(body)
+        return ["no FAQPage JSON-LD"] if doc.faq_items.empty?
+
+        Audit::Checks.faq_visible(doc)
+      end
+    end
+
+    # Well-formed sitemap (urlset or sitemapindex) whose URLs are on +origin+.
+    class SitemapMatcher < Matcher
+      def initialize(origin)
+        super()
+        @origin = origin
+      end
+
+      def description
+        "a valid sitemap#{" on #{@origin}" if @origin}"
+      end
+
+      private
+
+      def check(body)
+        Audit::Checks.sitemap(body, origin: @origin && "#{@origin.chomp("/")}/").first
+      end
+    end
+
+    # robots.txt lets +user_agent+ fetch +path+.
+    class RobotsMatcher < Matcher
+      def initialize(user_agent, path)
+        super()
+        @user_agent = user_agent
+        @path = path
+      end
+
+      def description
+        "robots.txt to allow #{@user_agent} to fetch #{@path}"
+      end
+
+      def failure_message_when_negated
+        "expected robots.txt to disallow #{@user_agent} #{@path}, but it is allowed"
+      end
+
+      private
+
+      def check(body)
+        evaluator = Robots::Evaluator.new(body)
+        return [] if evaluator.allowed?(@user_agent, @path)
+
+        rule = evaluator.matching_rule(@user_agent, @path)
+        ["#{rule.first.to_s.capitalize}: #{rule.last} applies (group #{evaluator.group_token(@user_agent)})"]
+      end
+    end
+
+    # Matcher methods; included into request specs automatically when RSpec is loaded.
+    module Matchers
+      include SeoGeo::Testing::EnvironmentHelper
+      # @param url [String]
+      def have_seo_geo_canonical(url) # rubocop:disable Naming/PredicateName
+        CanonicalMatcher.new(url)
+      end
+
+      def have_seo_geo_single_title # rubocop:disable Naming/PredicateName
+        SingleTitleMatcher.new
+      end
+
+      def have_seo_geo_faq_matching_visible_text # rubocop:disable Naming/PredicateName
+        FaqMatcher.new
+      end
+
+      # @param origin [String, nil]
+      def be_seo_geo_valid_sitemap(origin: nil)
+        SitemapMatcher.new(origin)
+      end
+
+      # @param user_agent [String]
+      # @param path [String]
+      def seo_geo_robots_allow(user_agent, path)
+        RobotsMatcher.new(user_agent, path)
+      end
+    end
+  end
+end
+
+if defined?(::RSpec) && ::RSpec.respond_to?(:configure)
+  ::RSpec.configure do |config|
+    config.include SeoGeo::RSpec::Matchers, type: :request
+    config.include SeoGeo::RSpec::Matchers, type: :controller
+  end
+end

data/lib/seo_geo/safe_regexp.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SeoGeo
+  # Matches configuration Regexps (+og_image.param_constraints+, +noindex_paths+, +sitemap.exclude+) against
+  # request-controlled strings with a per-regexp timeout, so a backtracking pattern such as
+  # +/\A(a+)+\1\z/+ cannot hold a request worker. +Regexp.timeout+ is nil by default (Rails 7.2 included).
+  #
+  # Callers choose what a timeout means; seo_geo always resolves it to the restrictive answer
+  # (OG param => 400, noindex path => noindex, exclusion => excluded).
+  module SafeRegexp
+    # Seconds a single match may run.
+    TIMEOUT = 0.05
+    # Longer input is never handed to a configuration Regexp.
+    MAX_INPUT = 4096
+
+    # Raised (and only raised) for the input-length cap; Regexp::TimeoutError covers slow matches.
+    class TooLong < StandardError; end
+
+    @cache = {}
+    @lock = Mutex.new
+
+    module_function
+
+    # @param regexp [Regexp]
+    # @param string [String]
+    # @raise [Regexp::TimeoutError, TooLong]
+    # @return [MatchData, nil]
+    def match(regexp, string)
+      raise TooLong, "input longer than #{MAX_INPUT} characters" if string.length > MAX_INPUT
+
+      bounded(regexp).match(string)
+    end
+
+    # @param regexp [Regexp]
+    # @param string [String]
+    # @param on_timeout [Boolean] answer when the match times out or the input is too long
+    # @return [Boolean]
+    def match?(regexp, string, on_timeout:)
+      !match(regexp, string).nil?
+    rescue Regexp::TimeoutError, TooLong
+      on_timeout
+    end
+
+    # @return [Regexp] a copy of +regexp+ carrying {TIMEOUT}, cached per source and options
+    def bounded(regexp)
+      key = [regexp.source, regexp.options]
+      @lock.synchronize { @cache[key] ||= Regexp.new(regexp.source, regexp.options, timeout: TIMEOUT) }
+    end
+  end
+end