farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/engine/shared/trie.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/internal/copyable"
+require "farce/shareable"
+require "farce/strict"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Portable immutable backend for {Farce::Strict::Trie}.
+    class PortableTrie
+      attr_reader :stats
+
+      EMPTY_CAPTURES       = [].freeze
+      EMPTY_NAMED_CAPTURES = {}.freeze
+
+      class Node
+        EMPTY_STATIC = {}.freeze
+
+        attr_reader :dynamic, :dynamic_index, :fast_static, :static, :static_depth, :stride, :tokens
+
+        def initialize
+          @static        = {}
+          @dynamic       = []
+          @dynamic_index = {}
+          @tokens        = []
+          @fast_static   = nil
+          @static_depth  = 0
+          @stride        = 1
+        end
+
+        def measure_static_depth
+          @static_depth =
+            if @dynamic.empty? && @tokens.empty? && !@static.empty?
+              1 + @static.each_value.map(&:static_depth).min
+            else
+              0
+            end
+        end
+
+        def optimize
+          return if @static_depth <= 1
+
+          @stride  = @static_depth
+          frontier = [[nil, self]]
+          @stride.times do
+            next_frontier = []
+            frontier.each do |prefix, node|
+              if node.static.length == 1
+                character, child = node.static.first
+                prefix = prefix ? prefix << character : String.new(character)
+                next_frontier << [prefix, child]
+              else
+                node.static.each do |character, child|
+                  next_prefix = prefix ? prefix + character : String.new(character)
+                  next_frontier << [next_prefix, child]
+                end
+              end
+            end
+            frontier = next_frontier
+          end
+          @fast_static = frontier.to_h { |prefix, node| [prefix.freeze, node] }.freeze
+          @static = EMPTY_STATIC
+        end
+
+        def freeze
+          @static.freeze
+          @dynamic.each(&:freeze)
+          @dynamic.freeze
+          @dynamic_index = nil
+          @tokens.freeze
+          super
+        end
+      end
+      private_constant :Node
+
+      def initialize(entries, tokens)
+        validate_array!(entries, "entries")
+        validate_array!(tokens, "tokens")
+        validate_tokens!(tokens)
+
+        @tokens      = Array.new(tokens).freeze
+        @root        = Node.new
+        nodes        = [@root]
+        static_edges = 0
+        regexp_edges = 0
+
+        Array.new(entries).each do |entry|
+          validate_array!(entry, "entry")
+          raise ArgumentError, "entry must contain parts and a token ID" unless entry.length == 2
+
+          parts, token_id = entry
+          validate_array!(parts, "parts")
+          unless token_id.is_a?(Integer) && token_id >= 0 && token_id < @tokens.length
+            raise ArgumentError, "token ID is out of range: #{token_id.inspect}"
+          end
+
+          node = @root
+          Array.new(parts).each do |part|
+            case part
+            when String
+              literal = String.new(part)
+              validate_encoding!(literal, "edge")
+              literal.each_char do |character|
+                child = node.static[character]
+                unless child
+                  child = Node.new
+                  node.static[character.freeze] = child
+                  nodes << child
+                  static_edges += 1
+                end
+                node = child
+              end
+            when Regexp
+              key = regexp_key(part)
+              child = node.dynamic_index[key]
+              unless child
+                child = Node.new
+                node.dynamic << [anchor(part), child]
+                node.dynamic_index[key] = child
+                nodes << child
+                regexp_edges += 1
+              end
+              node = child
+            else
+              raise TypeError, "edge must be a String or Regexp, got #{part.class}"
+            end
+          end
+          node.tokens << token_id
+        end
+
+        nodes.reverse_each(&:measure_static_depth)
+        frontier = [@root]
+        until frontier.empty?
+          node = frontier.pop
+          node.optimize
+          (node.fast_static || node.static).each_value { |child| frontier << child }
+          node.dynamic.each { |edge| frontier << edge.last }
+        end
+        nodes.each(&:freeze)
+        @stats = {
+          nodes:               nodes.length,
+          static_edges:,
+          regexp_edges:,
+          native_regexp_edges: 0,
+          ruby_regexp_edges:   regexp_edges,
+        }.freeze
+        freeze
+      end
+
+      def match(input) = find(input, all: false, peek: false)
+      def match_all(input) = find(input, all: true, peek: false)
+      def peek(input) = find(input, all: false, peek: true)
+      def peek_all(input) = find(input, all: true, peek: true)
+
+      def each_match(input, &block)
+        return enum_for(__method__, input) unless block
+
+        each_result(input, peek: false, deduplicate: true, &block)
+        self
+      end
+
+      def each_peek(input, &block)
+        return enum_for(__method__, input) unless block
+
+        each_result(input, peek: true, deduplicate: true, &block)
+        self
+      end
+
+      private
+
+      def anchor(regexp)
+        compile_regexp("\\G(?:#{regexp.source})", regexp)
+      rescue RegexpError
+        compile_regexp("\\G(?:#{regexp.source}\n)", regexp)
+      end
+
+      def compile_regexp(source, regexp)
+        if regexp.respond_to?(:timeout)
+          Regexp.new(source, regexp.options, timeout: regexp.timeout).freeze
+        else
+          Regexp.new(source, regexp.options).freeze
+        end
+      end
+
+      def regexp_key(regexp)
+        timeout = regexp.timeout if regexp.respond_to?(:timeout)
+        [regexp.source, regexp.options, regexp.encoding, timeout].freeze
+      end
+
+      def validate_array!(value, name)
+        raise TypeError, "#{name} must be an Array" unless value.is_a?(Array)
+      end
+
+      def validate_tokens!(tokens)
+        seen = {}.compare_by_identity
+        tokens.each do |token|
+          raise Ractor::IsolationError, "token is not Ractor-shareable" unless Ractor.shareable?(token)
+          raise ArgumentError, "tokens must be unique by identity" if seen.key?(token)
+
+          seen[token] = true
+        end
+      end
+
+      def validate_encoding!(string, label)
+        return if string.valid_encoding?
+
+        raise ArgumentError, "#{label} has an invalid #{string.encoding} byte sequence"
+      end
+
+      def find(input, all:, peek:)
+        results = [] if all
+        each_result(input, peek:, deduplicate: all) do |token, captures, named, suffix|
+          tuple = [token, captures, named, suffix]
+          return tuple unless all
+
+          results << tuple
+        end
+        all ? results : nil
+      end
+
+      def each_result(input, peek:, deduplicate:)
+        raise TypeError, "input must be a String" unless input.is_a?(String)
+        input = String.new(input)
+        validate_encoding!(input, "input")
+
+        input_length = input.length
+        seen = {} if deduplicate
+        stack = [[@root, 0, EMPTY_CAPTURES, EMPTY_NAMED_CAPTURES, 0, 0]]
+
+        until stack.empty?
+          node, position, captures, named, phase, index = stack.pop
+          case phase
+          when 0
+            stack << [node, position, captures, named, 1, 0]
+            if node.fast_static
+              key = input[position, node.stride]
+              if key && (child = node.fast_static[key])
+                stack << [child, position + node.stride, captures, named, 0, 0]
+              end
+            elsif position < input_length && (child = node.static[input[position]])
+              stack << [child, position + 1, captures, named, 0, 0]
+            end
+          when 1
+            if index < node.dynamic.length
+              regexp, child = node.dynamic[index]
+              stack << [node, position, captures, named, 1, index + 1]
+              if (matched = regexp.match(input, position))
+                stack << [
+                  child,
+                  matched.end(0),
+                  captures + matched.captures,
+                  merge_named_captures(named, matched.named_captures),
+                  0,
+                  0
+                ]
+              end
+            elsif (peek || position == input_length) && !node.tokens.empty?
+              node.tokens.each do |token_id|
+                next if deduplicate && seen.key?(token_id)
+
+                seen[token_id] = true if deduplicate
+                yield(
+                  @tokens.fetch(token_id),
+                  captures.map { |value| value&.dup },
+                  copy_named_captures(named),
+                  input[position..] || +""
+                )
+              end
+            end
+          end
+        end
+      end
+
+      def merge_named_captures(base, additions)
+        return base if additions.empty?
+
+        merged = base.dup
+        additions.each do |name, value|
+          unless merged.key?(name)
+            merged[name] = value
+            next
+          end
+
+          previous = merged[name]
+          merged[name] = previous.is_a?(Array) ? previous + [value] : [previous, value]
+        end
+        merged
+      end
+
+      def copy_named_captures(named)
+        named.to_h do |name, value|
+          copied = if value.is_a?(Array)
+                     value.map { |element| element&.dup }
+                   else
+                     value&.dup
+                   end
+          [name.dup, copied]
+        end
+      end
+    end
+  end
+
+  module Strict
+    unless const_defined?(:Trie, false)
+      # Portable implementation used on JRuby and TruffleRuby.
+      class Trie < Internal::PortableTrie
+        include Internal::Copyable
+        include Shareable::Immutable
+      end
+    end
+  end
+end
+
+require "farce/engine/shared/trie_builder"

data/lib/farce/engine/shared/trie_builder.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/internal/copyable"
+require "farce/shareable"
+
+module Farce
+  module Strict
+    # An immutable Ractor-shareable trie for String and Regexp chains.
+    #
+    # Build a trie with {.build} or {Builder}. Published tries do not change.
+    # A reusable builder can publish additional independent snapshots.
+    #
+    # Static edges take precedence over regexp edges. Regexp edges retain their
+    # insertion order. `peek` searches descendants before returning a shorter
+    # terminal match. A regexp edge is atomic. Later edges cannot make a regexp
+    # choose a different endpoint.
+    #
+    # Tokens must already be Ractor-shareable. They are stored and returned
+    # unchanged. Equal but different token objects remain separate. Reusing the
+    # same token object produces at most one result per lookup.
+    #
+    # Each result is `[token, positional_captures, named_captures, suffix]`.
+    # Exact matches have an empty suffix. Capture arrays, hashes, strings, and
+    # suffixes are new mutable objects for each result. A capture string may
+    # be shared between the positional and named views within one result.
+    #
+    # Input and literal edges retain Ruby String encoding behavior. Invalid byte
+    # sequences are rejected. ASCII-8BIT strings provide binary matching.
+    # Incompatible literal encodings do not match. Regexp encoding errors retain
+    # Ruby's ordinary behavior.
+    #
+    # `dup` and `clone` return frozen, Ractor-shareable matchers with the same
+    # immutable graph and token objects. This also applies to
+    # `clone(freeze: false)`.
+    #
+    # @example Build and match a trie
+    #   routes = Farce::Strict::Trie.build do |builder|
+    #     builder.add(["/users/", /(?<id>\d+)/], :user)
+    #   end
+    #
+    #   routes.match("/users/12")
+    #   # => [:user, ["12"], { "id" => "12" }, ""]
+    #
+    # @!method match(input)
+    #   Return the first exact match.
+    #   @param input [String]
+    #   @return [Array(Object, Array<String, nil>, Hash{String => Object}, String), nil]
+    #
+    # @!method match_all(input)
+    #   Return every exact match in traversal order.
+    #   @param input [String]
+    #   @return [Array<Array>]
+    #
+    # @!method peek(input)
+    #   Return the first prefix match.
+    #   @param input [String]
+    #   @return [Array(Object, Array<String, nil>, Hash{String => Object}, String), nil]
+    #
+    # @!method peek_all(input)
+    #   Return every prefix match in traversal order.
+    #   @param input [String]
+    #   @return [Array<Array>]
+    #
+    # @!method each_match(input)
+    #   Yield each exact match without first collecting every result.
+    #   Each yield has four arguments: token, positional captures, named
+    #   captures, and suffix.
+    #   @param input [String]
+    #   @yieldparam token [Object]
+    #   @yieldparam positional_captures [Array<String, nil>]
+    #   @yieldparam named_captures [Hash{String => Object}]
+    #   @yieldparam suffix [String]
+    #   @return [Trie, Enumerator] self after normal exhaustion, or an Enumerator
+    #     when no block is given
+    #
+    # @!method each_peek(input)
+    #   Yield each prefix match without first collecting every result.
+    #   Each yield has four arguments: token, positional captures, named
+    #   captures, and suffix.
+    #   @param input [String]
+    #   @yieldparam token [Object]
+    #   @yieldparam positional_captures [Array<String, nil>]
+    #   @yieldparam named_captures [Hash{String => Object}]
+    #   @yieldparam suffix [String]
+    #   @return [Trie, Enumerator] self after normal exhaustion, or an Enumerator
+    #     when no block is given
+    class Trie
+      include Internal::MarshalSupport::Reject
+      include Internal::Copyable unless ancestors.include?(Internal::Copyable)
+      include Shareable::Immutable unless ancestors.include?(Shareable::Immutable)
+
+      # Collects entries and publishes immutable {Trie} snapshots.
+      class Builder
+        # Create an empty builder.
+        def initialize
+          @entries = []
+        end
+
+        # @api private
+        def marshal_dump
+          entries = @entries.map { |parts, token| [parts, Internal::MarshalSupport.value(token)] }
+          [1, entries, frozen?]
+        end
+
+        # @api private
+        def marshal_load(data)
+          entries, frozen = Internal::MarshalSupport.payload(data, 2)
+          initialize
+          entries.each { |parts, token| add(parts, Internal::MarshalSupport.restore_value(token)) }
+          freeze if frozen
+        end
+
+        # Add a String and Regexp chain.
+        #
+        # Literal strings are copied immediately. The token is not copied or
+        # frozen and must already be Ractor-shareable. A published trie retains
+        # a plain semantic copy of each regexp, not caller-owned regexp state.
+        #
+        # @param parts [Array<String, Regexp>] ordered matcher edges
+        # @param token [Object] the object returned for a match
+        # @return [Builder] self
+        # @raise [TypeError] if parts or one of its elements has the wrong type
+        # @raise [ArgumentError] if a literal has an invalid byte sequence
+        # @raise [Ractor::IsolationError] if token is not Ractor-shareable
+        def add(parts, token)
+          raise TypeError, "parts must be an Array" unless parts.is_a?(Array)
+          raise Ractor::IsolationError, "token is not Ractor-shareable" unless Ractor.shareable?(token)
+
+          snapshot = Array.new(parts).map do |part|
+            case part
+            when String
+              snapshot_literal(part)
+            when Regexp
+              part
+            else
+              raise TypeError, "edge must be a String or Regexp, got #{part.class}"
+            end
+          end.freeze
+
+          @entries << [snapshot, token].freeze
+          self
+        end
+
+        # Publish an immutable snapshot of the current entries.
+        #
+        # Subsequent changes to the builder do not affect the returned trie.
+        #
+        # @return [Trie]
+        def build
+          tokens = []
+          token_ids = {}.compare_by_identity
+          entries = @entries.map do |parts, token|
+            unless token_ids.key?(token)
+              token_ids[token] = tokens.length
+              tokens << token
+            end
+            [parts.dup.freeze, token_ids.fetch(token)].freeze
+          end.freeze
+
+          Trie.send(:build_entries, entries, tokens.freeze)
+        end
+
+        private
+
+        def snapshot_literal(part)
+          literal = String.new(part)
+          raise ArgumentError, "edge has an invalid #{literal.encoding} byte sequence" unless literal.valid_encoding?
+
+          literal.freeze
+        end
+
+        def initialize_copy(other)
+          super
+          @entries = other.instance_variable_get(:@entries).dup
+        end
+      end
+
+      class << self
+        # Build an immutable trie.
+        #
+        # @yieldparam builder [Builder]
+        # @return [Trie]
+        def build
+          builder = Builder.new
+          yield builder if block_given?
+          builder.build
+        end
+
+        private
+
+        def build_entries(entries, tokens) = new(entries, tokens)
+
+        private :new
+      end
+    end
+  end
+end

data/lib/farce/engine/shared/unshareable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module Unshareable
+      def pin_to_current_ractor(object) = object
+      def prevent_copyable(object)      = object
+      def prevent_shareable(object)     = object
+    end
+  end
+end