ruby_routes 2.2.0 → 2.3.0

data/lib/ruby_routes/router.rb

@@ -1,210 +1,222 @@
+# frozen_string_literal: true
+
+require_relative 'utility/inflector_utility'
 require_relative 'utility/route_utility'
+require_relative 'router/http_helpers'
 
 module RubyRoutes
+  # RubyRoutes::Router
+  #
+  # Public DSL entrypoint for defining application routes.
+  #
+  # Usage:
+  #   router = RubyRoutes::Router.new do
+  #     get '/health', to: 'system#health'
+  #     resources :users
+  #     namespace :admin do
+  #       resources :posts
+  #     end
+  #   end
+  #
+  # Thread Safety:
+  #   Build routes at boot. Mutating after multiple threads start serving
+  #   requests is not supported.
+  #
+  # Responsibilities:
+  # - Provide Rails‑inspired DSL (get/post/put/patch/delete/match/root).
+  # - Define RESTful collections via `#resources` and singular via `#resource`.
+  # - Support scoping (namespace / scope / constraints / defaults).
+  # - Allow reusable blocks via concerns (`#concern` / `#concerns`).
+  # - Mount external Rack apps (`#mount`).
+  # - Delegate route object creation & storage to `RouteSet` / `RouteUtility`.
+  #
+  # Design Notes:
+  # - Scope stack is an array of shallow hashes (path/module/constraints/defaults).
+  # - Scopes are applied inner-first (reverse_each). For options (constraints/defaults),
+  #   inner values should override outer ones.
+  # - Options hashes passed by users are duplicated only when necessary
+  #   (see `build_route_options`) to reduce allocation churn.
+  #
+  # Public API Surface (Stable):
+  # - `#initialize` (block form)
+  # - HTTP verb helpers (`get/post/put/patch/delete/match`)
+  # - `#root`
+  # - `#resources` / `#resource`
+  # - `#namespace` / `#scope` / `#constraints` / `#defaults`
+  # - `#concern` / `#concerns`
+  # - `#mount`
+  #
+  # Internal / Subject to Change:
+  # - `#add_route`
+  # - `#apply_scope`
+  # - `#build_route_options`
+  # - `#push_scope`
+  #
+  # @api public
   class Router
+    VERBS_ALL = RubyRoutes::Constant::VERBS_ALL
+
     attr_reader :route_set
 
-    def initialize(&block)
-      @route_set = RouteSet.new
+    include RubyRoutes::Router::HttpHelpers
+
+    # Initialize the router.
+    #
+    # @param definition_block [Proc] The block to define routes.
+    def initialize(&definition_block)
+      @route_set   = RouteSet.new
       @route_utils = RubyRoutes::Utility::RouteUtility.new(@route_set)
       @scope_stack = []
-      @concerns = {}
-      instance_eval(&block) if block_given?
-    end
-
-    # Basic route definition
-    def get(path, options = {})
-      add_route(path, options.merge(via: :get))
-    end
-
-    def post(path, options = {})
-      add_route(path, options.merge(via: :post))
+      @concerns    = {}
+      instance_eval(&definition_block) if definition_block
     end
 
-    def put(path, options = {})
-      add_route(path, options.merge(via: :put))
+    # Build a finalized router.
+    #
+    # @param definition_block [Proc] The block to define routes.
+    # @return [Router] The finalized router.
+    def self.build(&definition_block)
+      new(&definition_block).finalize!
     end
 
-    def patch(path, options = {})
-      add_route(path, options.merge(via: :patch))
-    end
+    # Finalize router for DSL immutability.
+    #
+    # @return [Router] self.
+    def finalize!
+      return self if @frozen
 
-    def delete(path, options = {})
-      add_route(path, options.merge(via: :delete))
+      @frozen = true
+      @scope_stack.freeze
+      @concerns.freeze
+      self
     end
 
-    def match(path, options = {})
-      add_route(path, options)
+    # Check if the router is frozen.
+    #
+    # @return [Boolean] `true` if the router is frozen, `false` otherwise.
+    def frozen?
+      !!@frozen
     end
 
-    # Resources routing (Rails-like)
-    def resources(name, options = {}, &block)
-      singular = name.to_s.singularize
-      plural = (options[:path] || name.to_s.pluralize)
-      controller = options[:controller] || plural
-
-      # Collection routes
-      get "/#{plural}", options.merge(to: "#{controller}#index")
-      get "/#{plural}/new", options.merge(to: "#{controller}#new")
-      post "/#{plural}", options.merge(to: "#{controller}#create")
-
-      # Member routes
-      get "/#{plural}/:id", options.merge(to: "#{controller}#show")
-      get "/#{plural}/:id/edit", options.merge(to: "#{controller}#edit")
-      put "/#{plural}/:id", options.merge(to: "#{controller}#update")
-      patch "/#{plural}/:id", options.merge(to: "#{controller}#update")
-      delete "/#{plural}/:id", options.merge(to: "#{controller}#destroy")
-
-      # Nested resources if specified
-      if options[:nested]
-        nested_name = options[:nested]
-        nested_singular = nested_name.to_s.singularize
-        nested_plural = nested_name.to_s.pluralize
-
-        get "/#{plural}/:id/#{nested_plural}", options.merge(to: "#{nested_plural}#index")
-        get "/#{plural}/:id/#{nested_plural}/new", options.merge(to: "#{nested_plural}#new")
-        post "/#{plural}/:id/#{nested_plural}", options.merge(to: "#{nested_plural}#create")
-        get "/#{plural}/:id/#{nested_plural}/:nested_id", options.merge(to: "#{nested_plural}#show")
-        get "/#{plural}/:id/#{nested_plural}/:nested_id/edit", options.merge(to: "#{nested_plural}#edit")
-        put "/#{plural}/:id/#{nested_plural}/:nested_id", options.merge(to: "#{nested_plural}#update")
-        patch "/#{plural}/:id/#{nested_plural}/:nested_id", options.merge(to: "#{nested_plural}#update")
-        delete "/#{plural}/:id/#{nested_plural}/:nested_id", options.merge(to: "#{nested_plural}#destroy")
-      end
-
-      # Handle concerns if block is given
-      if block_given?
-        # Push a scope for nested resources
-        @scope_stack.push({ path: "/#{plural}/:id" })
-        # Execute the block in the context of this router instance
-        instance_eval(&block)
-        @scope_stack.pop
-      end
-    end
-
-    def resource(name, options = {})
-      singular = name.to_s.singularize
-
-      get "/#{singular}", options.merge(to: "#{singular}#show")
-      get "/#{singular}/new", options.merge(to: "#{singular}#new")
-      post "/#{singular}", options.merge(to: "#{singular}#create")
-      get "/#{singular}/edit", options.merge(to: "#{singular}#edit")
-      put "/#{singular}", options.merge(to: "#{singular}#update")
-      patch "/#{singular}", options.merge(to: "#{singular}#update")
-      delete "/#{singular}", options.merge(to: "#{singular}#destroy")
-    end
-
-    # Namespace support
-    def namespace(name, options = {}, &block)
-      @scope_stack.push({ path: "/#{name}", module: name })
-
-      if block_given?
-        instance_eval(&block)
-      end
-
-      @scope_stack.pop
-    end
-
-    # Scope support
-    def scope(options_or_path = {}, &block)
-      # Handle the case where the first argument is a string (path)
-      options = if options_or_path.is_a?(String)
-                  { path: options_or_path }
-                else
-                  options_or_path
-                end
-
-      @scope_stack.push(options)
-
-      if block_given?
-        instance_eval(&block)
-      end
-
-      @scope_stack.pop
-    end
-
-    # Root route
+    # Define a root route.
+    #
+    # @param options [Hash] The options for the root route.
+    # @return [Router] self.
     def root(options = {})
-      add_route("/", options.merge(via: :get))
-    end
-
-    # Concerns (reusable route groups)
-    def concerns(*names, &block)
-      names.each do |name|
-        concern = @concerns[name]
-        raise "Concern '#{name}' not found" unless concern
-
-        instance_eval(&concern)
-      end
-
-      if block_given?
-        instance_eval(&block)
+      add_route('/', build_route_options(options, :get))
+      self
+    end
+
+    # ---- RESTful Resources -------------------------------------------------
+
+    # Define RESTful resources.
+    #
+    # @param resource_name [Symbol, String] The resource name.
+    # @param options [Hash] The options for the resource.
+    # @param nested_block [Proc] The block for nested routes.
+    # @return [Router] self.
+    def resources(resource_name, options = {}, &nested_block)
+      define_resource_routes(resource_name, options, &nested_block)
+    end
+
+    # Define a singular resource.
+    #
+    # @param resource_name [Symbol, String] The resource name.
+    # @param options [Hash] The options for the resource.
+    # @return [Router] self.
+    def resource(resource_name, options = {})
+      singular   = RubyRoutes::Utility::InflectorUtility.singularize(resource_name.to_s)
+      controller = options[:controller] || singular
+      define_singular_routes(singular, controller, options)
+    end
+
+    # ---- Scoping & Namespaces ----------------------------------------------
+
+    # Define a namespace.
+    #
+    # @param namespace_name [Symbol, String] The namespace name.
+    # @param options [Hash] The options for the namespace.
+    # @param block [Proc] The block for nested routes.
+    # @return [Router] self.
+    def namespace(namespace_name, options = {}, &block)
+      push_scope({ path: "/#{namespace_name}", module: namespace_name }.merge(options)) do
+        instance_eval(&block) if block
       end
     end
 
-    def concern(name, &block)
-      @concerns[name] = block
-    end
-
-    # Route constraints
-    def constraints(constraints = {}, &block)
-      @scope_stack.push({ constraints: constraints })
-
-      if block_given?
-        instance_eval(&block)
+    # Define a scope.
+    #
+    # @param options_or_path [Hash, String] The options or path for the scope.
+    # @param block [Proc] The block for nested routes.
+    # @return [Router] self.
+    def scope(options_or_path = {}, &block)
+      scope_entry = options_or_path.is_a?(String) ? { path: options_or_path } : options_or_path
+      push_scope(scope_entry) { instance_eval(&block) if block }
+    end
+
+    # Define constraints.
+    #
+    # @param constraints_hash [Hash] The constraints for the scope.
+    # @param block [Proc] The block for nested routes.
+    # @return [Router] self.
+    def constraints(constraints_hash = {}, &block)
+      push_scope(constraints: constraints_hash) { instance_eval(&block) if block }
+    end
+
+    # Define defaults.
+    #
+    # @param defaults_hash [Hash] The default values for the scope.
+    # @param block [Proc] The block for nested routes.
+    # @return [Router] self.
+    def defaults(defaults_hash = {}, &block)
+      push_scope(defaults: defaults_hash) { instance_eval(&block) if block }
+    end
+
+    # ---- Concerns ----------------------------------------------------------
+
+    # Define a concern.
+    #
+    # @param concern_name [Symbol] The concern name.
+    # @param block [Proc] The block defining the concern.
+    # @return [void]
+    def concern(concern_name, &block)
+      ensure_unfrozen!
+      @concerns[concern_name] = block
+    end
+
+    # Use concerns.
+    #
+    # @param concern_names [Array<Symbol>] The names of the concerns to use.
+    # @param block [Proc] The block for additional routes.
+    # @return [void]
+    def concerns(*concern_names, &block)
+      concern_names.each do |name|
+        concern_block = @concerns[name]
+        raise "Concern '#{name}' not found" unless concern_block
+
+        instance_eval(&concern_block)
       end
-
-      @scope_stack.pop
+      instance_eval(&block) if block
     end
 
-    # Defaults
-    def defaults(defaults = {}, &block)
-      @scope_stack.push({ defaults: defaults })
-
-      if block_given?
-        instance_eval(&block)
-      end
-
-      @scope_stack.pop
-    end
+    # ---- Mounting ----------------------------------------------------------
 
-    # Mount other applications
+    # Mount an app.
+    #
+    # @param app [Object] The app to mount.
+    # @param at [String, nil] The path to mount the app at.
+    # @return [void]
     def mount(app, at: nil)
-      path = at || "/#{app}"
-      add_route("#{path}/*path", to: app, via: :all)
-    end
-
-    private
-
-    def add_route(path, options={})
-      scoped = apply_scope(path, options)
-      @route_utils.define(scoped[:path], scoped)
-    end
-
-    def apply_scope(path, options)
-      scoped_options = options.dup
-      scoped_path = path
-
-      @scope_stack.reverse_each do |scope|
-        if scope[:path]
-          scoped_path = "#{scope[:path]}#{scoped_path}"
-        end
-
-        if scope[:module] && scoped_options[:to]
-          controller = scoped_options[:to].to_s.split('#').first
-          scoped_options[:to] = "#{scope[:module]}/#{controller}##{scoped_options[:to].to_s.split('#').last}"
-        end
-
-        if scope[:constraints]
-          scoped_options[:constraints] = (scoped_options[:constraints] || {}).merge(scope[:constraints])
-        end
-
-        if scope[:defaults]
-          scoped_options[:defaults] = (scoped_options[:defaults] || {}).merge(scope[:defaults])
-        end
-      end
-
-      scoped_options[:path] = scoped_path
-      scoped_options
+      ensure_unfrozen!
+      mount_path = at || "/#{app}"
+      defaults = { _mounted_app: app }
+      add_route(
+        "#{mount_path}/*path",
+        controller: 'mounted',
+        action: :call,
+        via: VERBS_ALL,
+        defaults: defaults
+      )
     end
   end
 end

data/lib/ruby_routes/segment.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'segments/base_segment'
 require_relative 'segments/dynamic_segment'
 require_relative 'segments/static_segment'
@@ -5,16 +7,34 @@ require_relative 'segments/wildcard_segment'
 require_relative 'constant'
 
 module RubyRoutes
+  # Segment
+  #
+  # Factory wrapper that selects the correct concrete Segment subclass
+  # (Static / Dynamic / Wildcard) based on the first character of a raw
+  # path token:
+  # - ":" → DynamicSegment (named param, e.g. :id)
+  # - "*" → WildcardSegment (greedy splat, e.g. *path)
+  # - otherwise → StaticSegment (literal text)
+  #
+  # It delegates byte‑based dispatch to RubyRoutes::Constant::SEGMENTS
+  # for O(1) lookup without multiple string comparisons.
+  #
+  # @api internal
   class Segment
+    # Build an appropriate segment instance for the provided token.
+    #
+    # @param text [String, Symbol, #to_s] raw segment token
+    # @return [RubyRoutes::Segments::BaseSegment]
+    #
+    # @example
+    #   Segment.for(":id")    # => DynamicSegment
+    #   Segment.for("*files") # => WildcardSegment
+    #   Segment.for("users")  # => StaticSegment
     def self.for(text)
-      t = text.to_s
-      key = t.empty? ? :default : t.getbyte(0)
-      segment = RubyRoutes::Constant::SEGMENTS[key] || RubyRoutes::Constant::SEGMENTS[:default]
-      segment.new(t)
-    end
-
-    def wildcard?
-      false
+      segment_text  = text.to_s
+      segment_key   = segment_text.empty? ? :default : segment_text.getbyte(0)
+      segment_class = RubyRoutes::Constant::SEGMENTS[segment_key] || RubyRoutes::Constant::SEGMENTS[:default]
+      segment_class.new(segment_text)
     end
   end
 end

data/lib/ruby_routes/segments/base_segment.rb

@@ -1,19 +1,55 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module Segments
+    # BaseSegment
+    #
+    # Abstract superclass for all parsed route path segments.
+    # Concrete subclasses implement:
+    # - StaticSegment: literal path component
+    # - DynamicSegment: parameter capture (e.g. :id)
+    # - WildcardSegment: greedy capture (e.g. *path)
+    #
+    # Responsibilities shared by subclasses:
+    # - Supplying a child node in the radix tree (ensure_child)
+    # - Participating in traversal / matching (match)
+    #
+    # Subclasses must override #ensure_child and #match.
+    #
+    # @api internal
     class BaseSegment
-      def initialize(text = nil)
-        @text = text.to_s if text
+      # @param raw_segment_text [String, Symbol, nil]
+      def initialize(raw_segment_text = nil)
+        @raw_text = raw_segment_text.to_s if raw_segment_text
       end
 
+      # Indicates whether this segment is a wildcard (greedy) segment.
+      #
+      # @return [Boolean]
       def wildcard?
         false
       end
 
-      def ensure_child(current)
+      # Ensure the proper child node exists beneath +parent_node+ for this segment
+      # and return it.
+      #
+      # @param parent_node [Object] radix tree node (implementation-specific)
+      # @return [Object] the (possibly newly-created) child node
+      # @raise [NotImplementedError] when not overridden
+      def ensure_child(parent_node)
         raise NotImplementedError, "#{self.class}#ensure_child must be implemented"
       end
 
-      def match(_node, _text, _idx, _segments, _params)
+      # Attempt to match this segment during traversal.
+      #
+      # @param current_node [Object] the current radix node
+      # @param incoming_segment_text [String] the path component being matched
+      # @param _segment_index [Integer] index of the component in the path (unused here)
+      # @param _all_segments [Array<String>] full list of segments (unused here)
+      # @param _captured_params [Hash, nil] params hash to populate (unused here)
+      # @return [Array<(Object, Boolean)>] [next_node, stop_traversal]
+      # @raise [NotImplementedError] when not overridden
+      def match(current_node, incoming_segment_text, _segment_index, _all_segments, _captured_params)
         raise NotImplementedError, "#{self.class}#match must be implemented"
       end
     end

data/lib/ruby_routes/segments/dynamic_segment.rb

@@ -1,22 +1,58 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module Segments
+    # DynamicSegment
+    #
+    # Represents a single dynamic (named) path component in a route
+    # definition (e.g. ":id" in "/users/:id").
+    #
+    # Responsibilities:
+    # - Ensures a dynamic_child node exists in the radix tree for traversal.
+    # - On match, captures the actual segment text into the params hash
+    #   using the parameter name (without the leading colon).
+    #
+    # Matching Behavior:
+    # - Succeeds if the current radix node has a dynamic_child.
+    # - Does NOT stop traversal (returns false as second tuple value).
+    #
+    # Returned tuple from #match:
+    #   [next_node, stop_traversal_flag]
+    #
+    # @api internal
     class DynamicSegment < BaseSegment
-      def initialize(text)
-        @name = text[1..-1]
+      # @param raw_segment_text [String] raw token (e.g. ":id")
+      def initialize(raw_segment_text)
+        super(raw_segment_text)
+        @param_name = raw_segment_text[1..]
       end
 
-      def ensure_child(current)
-        current.dynamic_child ||= Node.new
-        current = current.dynamic_child
-        current.param_name = @name
-        current
+      # Ensure a dynamic child node under +parent_node+ and assign the
+      # parameter name to that node for later extraction.
+      #
+      # @param parent_node [Object] radix tree node
+      # @return [Object] the dynamic child node
+      def ensure_child(parent_node)
+        parent_node.dynamic_child ||= Node.new
+        dynamic_child_node = parent_node.dynamic_child
+        dynamic_child_node.param_name = @param_name
+        dynamic_child_node
       end
 
-      def match(node, text, _idx, _segments, params)
-        return [nil, false] unless node.dynamic_child
-        nxt = node.dynamic_child
-        params[nxt.param_name.to_s] = text if params
-        [nxt, false]
+      # Attempt to match this segment during traversal.
+      #
+      # @param current_node [Object] current radix node
+      # @param incoming_segment_text [String] actual path segment from request
+      # @param _segment_index [Integer] (unused)
+      # @param _all_segments [Array<String>] (unused)
+      # @param captured_params [Hash] params hash to populate
+      # @return [Array<(Object, Boolean)>] [next_node, stop_traversal=false]
+      def match(current_node, incoming_segment_text, _segment_index, _all_segments, captured_params)
+        return [nil, false] unless current_node.dynamic_child
+
+        dynamic_child_node = current_node.dynamic_child
+        captured_params[dynamic_child_node.param_name.to_s] = incoming_segment_text if captured_params
+        [dynamic_child_node, false]
       end
     end
   end

data/lib/ruby_routes/segments/static_segment.rb

@@ -1,17 +1,53 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module Segments
+    # StaticSegment
+    #
+    # Represents a literal (non-parameter) segment in a route path.
+    # Example: "users" in "/users/:id".
+    #
+    # Responsibilities:
+    # - Ensures a static child node exists under the current radix node
+    #   keyed by the literal segment text.
+    # - During traversal (#match), returns the child node for the incoming
+    #   path component if it exists.
+    #
+    # Matching Behavior:
+    # - Succeeds only when the exact literal exists as a child.
+    # - Never captures parameters (no changes to params hash).
+    # - Never stops traversal early (second tuple element = false).
+    #
+    # Returned tuple from #match:
+    #   [next_node, stop_traversal_flag]
+    #
+    # @api internal
     class StaticSegment < BaseSegment
-      def initialize(text)
-        @text = text
+      # @param raw_segment_text [String] literal segment token
+      def initialize(raw_segment_text)
+        super(raw_segment_text)
+        @literal_text = raw_segment_text
       end
 
-      def ensure_child(current)
-        current.static_children[@text] ||= Node.new
-        current.static_children[@text]
+      # Ensure a static child node for this literal under +parent_node+.
+      #
+      # @param parent_node [Object] radix tree node
+      # @return [Object] the static child node
+      def ensure_child(parent_node)
+        parent_node.static_children[@literal_text] ||= Node.new
+        parent_node.static_children[@literal_text]
       end
 
-      def match(node, text, _idx, _segments, _params)
-        [node.static_children[text], false]
+      # Attempt to match this literal segment.
+      #
+      # @param current_node [Object] current radix node
+      # @param incoming_segment_text [String] segment from request path
+      # @param _segment_index [Integer] (unused)
+      # @param _all_segments [Array<String>] (unused)
+      # @param _extracted_params [Hash] (unused, no params captured)
+      # @return [Array<(Object, Boolean)>] [next_node_or_nil, stop_traversal=false]
+      def match(current_node, incoming_segment_text, _segment_index, _all_segments, _extracted_params)
+        [current_node.static_children[incoming_segment_text], false]
       end
     end
   end