tarsier 0.1.0

data/lib/tarsier/router/compiler.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Tarsier
+  class Router
+    # Compiles routes into an optimized radix tree structure
+    # Routes are compiled at boot time for zero runtime overhead
+    class Compiler
+      attr_reader :trees
+
+      def initialize
+        # Separate tree per HTTP method for faster lookups
+        @trees = {}
+        @named_routes = {}
+        @compiled = false
+      end
+
+      # Add a route to the compiler
+      # @param route [Route] the route to add
+      def add(route)
+        raise InvalidRouteError, "Cannot add routes after compilation" if @compiled
+
+        tree = (@trees[route.method] ||= Node.new)
+        insert_route(tree, route, route.segments)
+
+        @named_routes[route.name] = route if route.name
+      end
+
+      # Compile all routes (call after all routes are added)
+      # Optimizes the tree structure for matching
+      def compile!
+        return if @compiled
+
+        @trees.each_value { |tree| optimize_tree(tree) }
+        @compiled = true
+        freeze_trees
+      end
+
+      # Check if routes have been compiled
+      # @return [Boolean]
+      def compiled?
+        @compiled
+      end
+
+      # Match a path against the compiled routes
+      # @param method [Symbol] HTTP method
+      # @param path [String] the path to match
+      # @return [Array<Route, Hash>, nil] route and params or nil
+      def match(method, path)
+        tree = @trees[method.to_s.upcase.to_sym]
+        return nil unless tree
+
+        segments = path == "/" ? [""] : path.split("/").drop(1)
+        match_segments(tree, segments, {})
+      end
+
+      # Get a named route
+      # @param name [Symbol] route name
+      # @return [Route, nil]
+      def named_route(name)
+        @named_routes[name]
+      end
+
+      # Generate a path for a named route
+      # @param name [Symbol] route name
+      # @param params [Hash] parameters
+      # @return [String]
+      def path_for(name, params = {})
+        route = @named_routes[name]
+        raise InvalidRouteError, "Unknown route: #{name}" unless route
+        route.generate(params)
+      end
+
+      # Get all routes
+      # @return [Array<Route>]
+      def routes
+        @trees.flat_map { |_method, tree| collect_routes(tree) }
+      end
+
+      private
+
+      def insert_route(node, route, segments, index = 0)
+        if index >= segments.length
+          raise InvalidRouteError, "Duplicate route: #{route.method} #{route.path}" if node.route
+          node.route = route
+          return
+        end
+
+        segment = segments[index]
+        child = find_or_create_child(node, segment)
+        insert_route(child, route, segments, index + 1)
+      end
+
+      def find_or_create_child(node, segment)
+        key = segment_key(segment)
+        existing = node.find_child(key)
+        return existing if existing
+
+        child = create_node(segment)
+        node.add_child(key, child)
+        node.invalidate_cache!
+        child
+      end
+
+      def segment_key(segment)
+        case segment[:type]
+        when :static then segment[:value]
+        when :param then ":#{segment[:name]}"
+        when :wildcard then "*#{segment[:name]}"
+        end
+      end
+
+      def create_node(segment)
+        case segment[:type]
+        when :static
+          Node.new(segment[:value], type: Node::STATIC)
+        when :param
+          Node.new("", type: Node::PARAM, param_name: segment[:name], constraint: segment[:constraint])
+        when :wildcard
+          Node.new("", type: Node::WILDCARD, param_name: segment[:name])
+        end
+      end
+
+      def match_segments(node, segments, params, index = 0)
+        # Terminal case: all segments consumed
+        if index >= segments.length
+          return [node.route, params] if node.terminal?
+          return nil
+        end
+
+        segment = segments[index]
+
+        # Try children in priority order (static > param > wildcard)
+        node.sorted_children.each do |child|
+          case child.type
+          when Node::STATIC
+            next unless child.segment == segment
+            result = match_segments(child, segments, params, index + 1)
+            return result if result
+          when Node::PARAM
+            captured = child.match?(segment)
+            next unless captured
+            result = match_segments(child, segments, params.merge(captured), index + 1)
+            return result if result
+          when Node::WILDCARD
+            # Wildcard captures rest of path
+            remaining = segments[index..].join("/")
+            new_params = params.merge(child.param_name => remaining)
+            return [child.route, new_params] if child.terminal?
+          end
+        end
+
+        nil
+      end
+
+      def optimize_tree(node)
+        # Sort children by priority and cache
+        node.sorted_children
+        node.children.each_value { |child| optimize_tree(child) }
+      end
+
+      def freeze_trees
+        @trees.freeze
+        @named_routes.freeze
+      end
+
+      def collect_routes(node, routes = [])
+        routes << node.route if node.route
+        node.children.each_value { |child| collect_routes(child, routes) }
+        routes
+      end
+    end
+  end
+end

data/lib/tarsier/router/node.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Tarsier
+  class Router
+    # Radix tree node for efficient route matching
+    # Supports static segments, parameters, wildcards, and constraints
+    class Node
+      # Node types for optimized matching
+      STATIC = :static
+      PARAM = :param
+      WILDCARD = :wildcard
+
+      attr_reader :segment, :type, :param_name, :constraint, :children
+      attr_accessor :route, :priority
+
+      # @param segment [String] the path segment this node represents
+      # @param type [Symbol] node type (:static, :param, :wildcard)
+      # @param param_name [String, nil] parameter name for dynamic segments
+      # @param constraint [Regexp, nil] constraint pattern for parameters
+      def initialize(segment = "", type: STATIC, param_name: nil, constraint: nil)
+        @segment = segment.freeze
+        @type = type
+        @param_name = param_name&.to_sym
+        @constraint = constraint
+        @children = {}
+        @route = nil
+        @priority = calculate_priority
+      end
+
+      # Add a child node
+      # @param key [String] the key for the child (segment or param marker)
+      # @param node [Node] the child node
+      # @return [Node] the added child node
+      def add_child(key, node)
+        @children[key] = node
+      end
+
+      # Find a child node by key
+      # @param key [String] the key to search for
+      # @return [Node, nil]
+      def find_child(key)
+        @children[key]
+      end
+
+      # Check if this node matches a segment
+      # @param segment [String] the segment to match
+      # @return [Boolean, Hash] false or hash with captured params
+      def match?(segment)
+        case @type
+        when STATIC
+          segment == @segment ? {} : false
+        when PARAM
+          match_param(segment)
+        when WILDCARD
+          { @param_name => segment }
+        end
+      end
+
+      # Check if this is a terminal node (has a route)
+      # @return [Boolean]
+      def terminal?
+        !@route.nil?
+      end
+
+      # Get sorted children for matching (static first, then params, then wildcards)
+      # @return [Array<Node>]
+      def sorted_children
+        @sorted_children ||= @children.values.sort_by(&:priority)
+      end
+
+      # Clear cached sorted children (call after adding children)
+      def invalidate_cache!
+        @sorted_children = nil
+      end
+
+      private
+
+      def match_param(segment)
+        return false if segment.nil? || segment.empty?
+
+        if @constraint
+          return false unless @constraint.match?(segment)
+        end
+
+        { @param_name => segment }
+      end
+
+      def calculate_priority
+        case @type
+        when STATIC then 0
+        when PARAM then 1
+        when WILDCARD then 2
+        end
+      end
+    end
+  end
+end

data/lib/tarsier/router/route.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Tarsier
+  class Router
+    # Represents a compiled route with handler and metadata
+    class Route
+      attr_reader :method, :path, :handler, :name, :constraints, :middleware, :options
+
+      # @param method [Symbol] HTTP method (:get, :post, etc.)
+      # @param path [String] the route path pattern
+      # @param handler [Object] the route handler (controller.action or proc)
+      # @param name [Symbol, nil] optional route name for URL generation
+      # @param constraints [Hash] parameter constraints
+      # @param middleware [Array] route-specific middleware
+      # @param options [Hash] additional route options
+      def initialize(method:, path:, handler:, name: nil, constraints: {}, middleware: [], **options)
+        @method = method.to_s.upcase.to_sym
+        @path = normalize_path(path)
+        @handler = handler
+        @name = name
+        @constraints = constraints
+        @middleware = middleware
+        @options = options
+        @segments = nil
+        @param_names = nil
+      end
+
+      # Parse path into segments for tree insertion
+      # @return [Array<Hash>] array of segment info hashes
+      def segments
+        @segments ||= parse_segments
+      end
+
+      # Get parameter names from the path
+      # @return [Array<Symbol>]
+      def param_names
+        @param_names ||= segments.select { |s| s[:type] != :static }.map { |s| s[:name] }
+      end
+
+      # Check if route has parameters
+      # @return [Boolean]
+      def dynamic?
+        segments.any? { |s| s[:type] != :static }
+      end
+
+      # Generate a path with given parameters
+      # @param params [Hash] parameters to interpolate
+      # @return [String] the generated path
+      def generate(params = {})
+        segments.map do |seg|
+          case seg[:type]
+          when :static
+            seg[:value]
+          when :param, :wildcard
+            value = params[seg[:name]] || params[seg[:name].to_s]
+            raise ArgumentError, "Missing required parameter: #{seg[:name]}" unless value
+            value.to_s
+          end
+        end.join("/").then { |p| "/#{p}" }
+      end
+
+      # Get the controller class if handler is controller-based
+      # @return [Class, nil]
+      def controller_class
+        return nil unless @handler.is_a?(Hash)
+        @handler[:controller]
+      end
+
+      # Get the action name if handler is controller-based
+      # @return [Symbol, nil]
+      def action_name
+        return nil unless @handler.is_a?(Hash)
+        @handler[:action]
+      end
+
+      # Check if handler is a proc/lambda
+      # @return [Boolean]
+      def proc_handler?
+        @handler.is_a?(Proc)
+      end
+
+      private
+
+      def normalize_path(path)
+        path = "/#{path}" unless path.start_with?("/")
+        path = path.chomp("/") unless path == "/"
+        path
+      end
+
+      def parse_segments
+        return [{ type: :static, value: "" }] if @path == "/"
+
+        @path.split("/").reject(&:empty?).map do |segment|
+          parse_segment(segment)
+        end
+      end
+
+      def parse_segment(segment)
+        case segment
+        when /\A:(\w+)(?:\{(.+)\})?\z/
+          # Parameter with optional constraint: :id or :id{\d+}
+          name = ::Regexp.last_match(1).to_sym
+          constraint = ::Regexp.last_match(2)
+          {
+            type: :param,
+            name: name,
+            constraint: constraint ? Regexp.new("\\A#{constraint}\\z") : @constraints[name]
+          }
+        when /\A\*(\w+)\z/
+          # Wildcard: *path
+          { type: :wildcard, name: ::Regexp.last_match(1).to_sym }
+        else
+          # Static segment
+          { type: :static, value: segment }
+        end
+      end
+    end
+  end
+end

data/lib/tarsier/router.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Tarsier
+  # High-performance router with compiled radix tree matching
+  # Supports RESTful resources, nested routes, and constraints
+  class Router
+    HTTP_METHODS = %i[get post put patch delete head options].freeze
+
+    attr_reader :compiler
+
+    def initialize
+      @compiler = Compiler.new
+      @scope_stack = []
+    end
+
+    # Define routes in a block
+    # @yield [self]
+    def draw(&block)
+      instance_eval(&block)
+      compile!
+      self
+    end
+
+    # Compile routes for optimized matching
+    def compile!
+      @compiler.compile!
+    end
+
+    # Match a request to a route
+    # @param method [Symbol, String] HTTP method
+    # @param path [String] request path
+    # @return [Array<Route, Hash>, nil] matched route and params
+    def match(method, path)
+      @compiler.match(method, path)
+    end
+
+    # Generate path for a named route
+    # @param name [Symbol] route name
+    # @param params [Hash] route parameters
+    # @return [String]
+    def path_for(name, params = {})
+      @compiler.path_for(name, params)
+    end
+
+    # Get all defined routes
+    # @return [Array<Route>]
+    def routes
+      @compiler.routes
+    end
+
+    # HTTP method helpers
+    HTTP_METHODS.each do |method|
+      define_method(method) do |path, to: nil, as: nil, constraints: {}, **options, &block|
+        add_route(method, path, to: to, as: as, constraints: constraints, **options, &block)
+      end
+    end
+
+    # Define RESTful resources
+    # @param name [Symbol] resource name
+    # @param only [Array<Symbol>] actions to include
+    # @param except [Array<Symbol>] actions to exclude
+    # @param controller [Symbol] controller name override
+    def resources(name, only: nil, except: nil, controller: nil, **options, &block)
+      controller_name = controller || name
+      actions = determine_actions(only, except)
+
+      resource_routes(name, controller_name, actions, **options)
+
+      if block_given?
+        scope(path: "#{name}/:#{singular(name)}_id") do
+          instance_eval(&block)
+        end
+      end
+    end
+
+    # Define a singular resource
+    # @param name [Symbol] resource name
+    def resource(name, only: nil, except: nil, controller: nil, **options, &block)
+      controller_name = controller || name.to_s.pluralize.to_sym
+      actions = determine_singular_actions(only, except)
+
+      singular_resource_routes(name, controller_name, actions, **options)
+
+      if block_given?
+        scope(path: name.to_s) do
+          instance_eval(&block)
+        end
+      end
+    end
+
+    # Create a route scope
+    # @param path [String] path prefix
+    # @param module_name [Symbol] controller module
+    # @param as [Symbol] name prefix
+    def scope(path: nil, module: nil, as: nil, **options, &block)
+      @scope_stack.push({
+        path: path,
+        module: binding.local_variable_get(:module),
+        as: as,
+        **options
+      })
+      instance_eval(&block)
+      @scope_stack.pop
+    end
+
+    # Namespace routes under a module
+    # @param name [Symbol] namespace name
+    def namespace(name, **options, &block)
+      scope(path: name.to_s, module: name, as: name, **options, &block)
+    end
+
+    # Mount a Rack application
+    # @param app [Object] Rack application
+    # @param at [String] mount path
+    def mount(app, at:)
+      path = "#{at.chomp('/')}/*path"
+      add_route(:get, path, to: app, mount: true)
+      add_route(:post, path, to: app, mount: true)
+      add_route(:put, path, to: app, mount: true)
+      add_route(:patch, path, to: app, mount: true)
+      add_route(:delete, path, to: app, mount: true)
+    end
+
+    # Root route helper
+    # @param to [Object] handler
+    def root(to:, as: :root)
+      get("/", to: to, as: as)
+    end
+
+    private
+
+    def add_route(method, path, to:, as: nil, constraints: {}, middleware: [], **options, &block)
+      full_path = build_path(path)
+      handler = resolve_handler(to, &block)
+      route_name = build_name(as)
+
+      route = Route.new(
+        method: method,
+        path: full_path,
+        handler: handler,
+        name: route_name,
+        constraints: constraints,
+        middleware: current_middleware + middleware,
+        **options
+      )
+
+      @compiler.add(route)
+    end
+
+    def build_path(path)
+      parts = @scope_stack.map { |s| s[:path] }.compact
+      parts << path
+      "/" + parts.join("/").gsub(%r{/+}, "/").gsub(%r{^/|/$}, "")
+    end
+
+    def build_name(name)
+      return nil unless name
+
+      parts = @scope_stack.map { |s| s[:as] }.compact
+      parts << name
+      parts.join("_").to_sym
+    end
+
+    def resolve_handler(to, &block)
+      return block if block_given?
+      return to if to.is_a?(Proc) || to.respond_to?(:call)
+
+      case to
+      when Hash
+        to
+      when String
+        # "controller#action" format
+        controller, action = to.split("#")
+        controller_class = resolve_controller(controller)
+        { controller: controller_class, action: action.to_sym }
+      else
+        raise InvalidRouteError, "Invalid handler: #{to.inspect}"
+      end
+    end
+
+    def resolve_controller(name)
+      parts = @scope_stack.map { |s| s[:module] }.compact
+      parts << name
+
+      class_name = parts.map { |p| camelize(p.to_s) }.join("::") + "Controller"
+
+      # Return the class name as a string for lazy loading
+      class_name
+    end
+
+    def current_middleware
+      @scope_stack.flat_map { |s| s[:middleware] || [] }
+    end
+
+    def determine_actions(only, except)
+      all = %i[index show new create edit update destroy]
+      actions = only ? (all & Array(only)) : all
+      except ? (actions - Array(except)) : actions
+    end
+
+    def determine_singular_actions(only, except)
+      all = %i[show new create edit update destroy]
+      actions = only ? (all & Array(only)) : all
+      except ? (actions - Array(except)) : actions
+    end
+
+    def resource_routes(name, controller, actions, **options)
+      path_name = name.to_s
+      singular_name = singular(name)
+
+      actions.each do |action|
+        case action
+        when :index
+          get(path_name, to: "#{controller}#index", as: name, **options)
+        when :show
+          get("#{path_name}/:id", to: "#{controller}#show", as: singular_name, **options)
+        when :new
+          get("#{path_name}/new", to: "#{controller}#new", as: :"new_#{singular_name}", **options)
+        when :create
+          post(path_name, to: "#{controller}#create", **options)
+        when :edit
+          get("#{path_name}/:id/edit", to: "#{controller}#edit", as: :"edit_#{singular_name}", **options)
+        when :update
+          put("#{path_name}/:id", to: "#{controller}#update", **options)
+          patch("#{path_name}/:id", to: "#{controller}#update", **options)
+        when :destroy
+          delete("#{path_name}/:id", to: "#{controller}#destroy", **options)
+        end
+      end
+    end
+
+    def singular_resource_routes(name, controller, actions, **options)
+      path_name = name.to_s
+
+      actions.each do |action|
+        case action
+        when :show
+          get(path_name, to: "#{controller}#show", as: name, **options)
+        when :new
+          get("#{path_name}/new", to: "#{controller}#new", as: :"new_#{name}", **options)
+        when :create
+          post(path_name, to: "#{controller}#create", **options)
+        when :edit
+          get("#{path_name}/edit", to: "#{controller}#edit", as: :"edit_#{name}", **options)
+        when :update
+          put(path_name, to: "#{controller}#update", **options)
+          patch(path_name, to: "#{controller}#update", **options)
+        when :destroy
+          delete(path_name, to: "#{controller}#destroy", **options)
+        end
+      end
+    end
+
+    def singular(name)
+      # Simple singularization - can be enhanced
+      word = name.to_s
+      if word.end_with?("ies")
+        word[0..-4] + "y"
+      elsif word.end_with?("es")
+        word[0..-3]
+      elsif word.end_with?("s")
+        word[0..-2]
+      else
+        word
+      end
+    end
+
+    def camelize(string)
+      string.split("_").map(&:capitalize).join
+    end
+  end
+end

data/lib/tarsier/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tarsier
+  VERSION = "0.1.0"
+end