ruby_routes 2.2.0 → 2.3.0

data/lib/ruby_routes/router/build_helpers.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative '../constant'
+
+module RubyRoutes
+  class Router
+    # BuildHelpers
+    #
+    # Small, focused utilities used while constructing routes and routers.
+    module BuildHelpers
+      # Build the router from recorded calls.
+      #
+      # This method creates a new `Router` instance, validates the recorded calls,
+      # finalizes the router (making it immutable), and returns the frozen instance.
+      #
+      # @return [Router] The finalized router.
+      def build
+        router = Router.new
+        validate_calls(@recorded_calls)
+        router.freeze
+        router.finalize!
+        router
+      end
+
+      # Build route options.
+      #
+      # This method creates a copy of the base options and conditionally adds
+      # the `:via` and `:to` keys if they are not already present or need to be overridden.
+      #
+      # @param base_options [Hash] The base options for the route.
+      # @param via_sym [Symbol, nil] The HTTP method (e.g., `:get`, `:post`).
+      # @param to_string [String, nil] The controller#action string (e.g., `"users#index"`).
+      # @return [Hash] The updated route options.
+      def build_route_options(base_options, via_sym = nil, to_string = nil)
+        force_via = !via_sym.nil? && base_options[:via] != via_sym
+        add_to    = !to_string.nil? && !base_options.key?(:to)
+        return base_options unless force_via || add_to
+
+        options_copy = base_options.dup
+        options_copy[:via] = via_sym if force_via
+        options_copy[:to]  = to_string if add_to
+        options_copy
+      end
+
+      # Helper: Build collection routes inside a resource scope.
+      #
+      # This method defines routes for collection-level actions (e.g., `index`, `new`, `create`)
+      # within the scope of a resource.
+      #
+      # @param opts [Hash] The options to apply to the routes.
+      # @param to_index [String] The controller#action string for the `index` action.
+      # @param to_new [String] The controller#action string for the `new` action.
+      # @param to_create [String] The controller#action string for the `create` action.
+      # @return [void]
+      def build_collection_routes(opts, to_index, to_new, to_create)
+        add_route('',     build_route_options(opts, :get,  to_index))
+        add_route('/new', build_route_options(opts, :get,  to_new))
+        add_route('',     build_route_options(opts, :post, to_create))
+      end
+
+      # Helper: Build member routes inside a resource scope.
+      #
+      # This method defines routes for member-level actions (e.g., `show`, `edit`, `update`, `destroy`)
+      # within the scope of a resource.
+      #
+      # @param opts [Hash] The options to apply to the routes.
+      # @param to_show [String] The controller#action string for the `show` action.
+      # @param to_edit [String] The controller#action string for the `edit` action.
+      # @param to_update [String] The controller#action string for the `update` action.
+      # @param to_destroy [String] The controller#action string for the `destroy` action.
+      # @return [void]
+      def build_member_routes(opts, to_show, to_edit, to_update, to_destroy)
+        add_route('/:id',      build_route_options(opts, :get,    to_show))
+        add_route('/:id/edit', build_route_options(opts, :get,    to_edit))
+        add_route('/:id',      opts.merge(via: %i[put patch], to: to_update))
+        add_route('/:id',      build_route_options(opts, :delete, to_destroy))
+      end
+
+      private
+
+      # Validate the recorded calls.
+      #
+      # This method ensures that all recorded calls use valid router methods
+      # as defined in `RubyRoutes::Constant::RECORDED_METHODS`.
+      #
+      # @param recorded_calls [Array<Array(Symbol, Array, Proc|NilClass)>]
+      #   The recorded calls to validate.
+      # @raise [ArgumentError] If any recorded call uses an invalid method.
+      # @return [void]
+      def validate_calls(recorded_calls)
+        allowed_router_methods = RubyRoutes::Constant::RECORDED_METHODS
+        recorded_calls.each do |(router_method, _arguments, _definition_block)|
+          unless router_method.is_a?(Symbol) && allowed_router_methods.include?(router_method)
+            raise ArgumentError, "Invalid router method: #{router_method.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_routes/router/builder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative '../constant'
+require_relative 'build_helpers'
+
+module RubyRoutes
+  class Router
+    # Builder
+    #
+    # Records routing DSL invocations without mutating a live Router.
+    # Later, `#build` replays the recorded calls on a fresh Router,
+    # finalizes it (immutability), and returns the frozen instance.
+    #
+    # Benefits:
+    # - Decouples route declaration time from Router instantiation.
+    # - Enables reuse (same blueprint -> multiple routers).
+    # - Safe to construct on boot and share across threads after build.
+    #
+    # Usage:
+    #   builder = RubyRoutes::Router::Builder.new do
+    #     namespace :api do
+    #       resources :users
+    #     end
+    #     get '/health', to: 'system#health'
+    #   end
+    #   router = builder.build  # finalized (router.frozen? == true)
+    #
+    # Supported DSL methods are mirrored here. Blocks are stored as Procs;
+    # serialization of blocks is not supported.
+    #
+    # @api internal
+    class Builder
+      include RubyRoutes::Router::BuildHelpers
+
+      # Array of recorded calls: [method_symbol, args_array, block].
+      #
+      # Each tuple contains:
+      # - The method name (as a Symbol).
+      # - The arguments (as an Array).
+      # - The block (as a Proc or `nil`).
+      #
+      # @return [Array<Array(Symbol, Array, Proc|NilClass)>]
+      #   A snapshot of the recorded calls to avoid external mutation.
+      def recorded_calls
+        @recorded_calls.dup.freeze
+      end
+
+      # Initialize the Builder.
+      #
+      # This method initializes the `@recorded_calls` array and optionally
+      # evaluates the provided block in the context of the Builder instance.
+      #
+      # @yield [definition_block] Runs the routing DSL in a recording context (optional).
+      # @return [void]
+      def initialize(&definition_block)
+        @recorded_calls = []
+        instance_eval(&definition_block) if definition_block
+      end
+
+      # ---- DSL Recording -------------------------------------------------
+      # Dynamically define methods for all DSL methods specified in
+      # `RubyRoutes::Constant::RECORDED_METHODS`. Each method records its
+      # invocation (method name, arguments, and block) in `@recorded_calls`.
+      #
+      # @param *arguments [Array] The arguments passed to the DSL method.
+      # @param definition_block [Proc, nil] The block passed to the DSL method.
+      # @return [nil]
+      RubyRoutes::Constant::RECORDED_METHODS.each do |method_name|
+        define_method(method_name) do |*arguments, &definition_block|
+          @recorded_calls << [__method__, arguments, definition_block]
+          nil
+        end
+      end
+
+      private
+
+      # Validate the recorded calls.
+      #
+      # This method ensures that all recorded calls use valid router methods
+      # as defined in `RubyRoutes::Constant::RECORDED_METHODS`.
+      #
+      # @param recorded_calls [Array<Array(Symbol, Array, Proc|NilClass)>]
+      #   The recorded calls to validate.
+      # @raise [ArgumentError] If any recorded call uses an invalid method.
+      # @return [void]
+      def validate_calls(recorded_calls)
+        allowed_router_methods = RubyRoutes::Constant::RECORDED_METHODS
+        recorded_calls.each do |(router_method, _arguments, _definition_block)|
+          unless router_method.is_a?(Symbol) && allowed_router_methods.include?(router_method)
+            raise ArgumentError, "Invalid router method: #{router_method.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_routes/router/http_helpers.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative 'build_helpers'
+require_relative 'scope_helpers'
+require_relative 'resource_helpers'
+
+module RubyRoutes
+  class Router
+    # HttpHelpers
+    #
+    # DSL methods exposing HTTP verb helpers (`get`, `post`, `put`, `patch`, `delete`, `match`)
+    # and small wiring helpers. Resource- and nested-related logic is delegated
+    # to `Router::ResourceHelpers` to keep this module focused.
+    #
+    # This module provides methods to define routes for various HTTP verbs, apply
+    # scopes, and manage route definitions. It also includes helper methods for
+    # defining singular resource routes.
+    module HttpHelpers
+      include RubyRoutes::Router::BuildHelpers
+      include RubyRoutes::Router::ScopeHelpers
+      include RubyRoutes::Router::ResourceHelpers
+
+      # ---- HTTP Verb Helpers -------------------------------------------------
+
+      # Define a GET route.
+      #
+      # @param path [String] The path for the route.
+      # @param options [Hash] The options for the route.
+      # @return [Router] Returns self for chaining.
+      def get(path, options = {})
+        add_route(path, build_route_options(options, :get))
+        self
+      end
+
+      # Define a POST route.
+      #
+      # @param path [String] The path for the route.
+      # @param options [Hash] The options for the route.
+      # @return [Router] Returns self for chaining.
+      def post(path, options = {})
+        add_route(path, build_route_options(options, :post))
+        self
+      end
+
+      # Define a PUT route.
+      #
+      # @param path [String] The path for the route.
+      # @param options [Hash] The options for the route.
+      # @return [Router] Returns self for chaining.
+      def put(path, options = {})
+        add_route(path, build_route_options(options, :put))
+        self
+      end
+
+      # Define a PATCH route.
+      #
+      # @param path [String] The path for the route.
+      # @param options [Hash] The options for the route.
+      # @return [Router] Returns self for chaining.
+      def patch(path, options = {})
+        add_route(path, build_route_options(options, :patch))
+        self
+      end
+
+      # Define a DELETE route.
+      #
+      # @param path [String] The path for the route.
+      # @param options [Hash] The options for the route.
+      # @return [Router] Returns self for chaining.
+      def delete(path, options = {})
+        add_route(path, build_route_options(options, :delete))
+        self
+      end
+
+      # Define a route for multiple HTTP methods.
+      #
+      # @param path [String] The path for the route.
+      # @param options [Hash] The options for the route.
+      #   - `:via` [Array<Symbol>] The HTTP methods to allow (e.g., `[:get, :post]`).
+      # @raise [ArgumentError] If `:via` is not provided or is empty.
+      # @return [Router] Returns self for chaining.
+      def match(path, options = {})
+        via = options[:via]
+        raise ArgumentError, 'match requires :via (e.g., via: [:get, :post])' if via.nil? || Array(via).empty?
+
+        add_route(path, options)
+        self
+      end
+
+      private
+
+      # Add a route to the router.
+      #
+      # This method applies the current scope to the route and defines it using
+      # the route utilities.
+      #
+      # @param path [String] The path for the route.
+      # @param options [Hash] The options for the route.
+      # @return [void]
+      def add_route(path, options = {})
+        ensure_unfrozen!
+        scoped = apply_scope(path, options)
+        @route_utils.define(scoped[:path], scoped)
+      end
+
+      # Ensure the router is not frozen.
+      #
+      # @raise [RuntimeError] If the router is frozen.
+      # @return [void]
+      def ensure_unfrozen!
+        raise 'Router finalized (immutable)' if @frozen
+      end
+
+      # Define routes for a singular resource.
+      #
+      # This method defines routes for a singular resource (e.g., `/profile`),
+      # including standard RESTful actions like `show`, `new`, `create`, `edit`,
+      # `update`, and `destroy`.
+      #
+      # @param singular [String] The name of the singular resource.
+      # @param controller [String] The name of the controller handling the resource.
+      # @param options [Hash] Additional options for the routes.
+      # @return [void]
+      def define_singular_routes(singular, controller, options)
+        get    "/#{singular}",       options.merge(to: "#{controller}#show")
+        get    "/#{singular}/new",   options.merge(to: "#{controller}#new")
+        post   "/#{singular}",       options.merge(to: "#{controller}#create")
+        get    "/#{singular}/edit",  options.merge(to: "#{controller}#edit")
+        put    "/#{singular}",       options.merge(to: "#{controller}#update")
+        patch  "/#{singular}",       options.merge(to: "#{controller}#update")
+        delete "/#{singular}",       options.merge(to: "#{controller}#destroy")
+      end
+    end
+  end
+end

data/lib/ruby_routes/router/resource_helpers.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative 'build_helpers'
+
+module RubyRoutes
+  class Router
+    # ResourceHelpers: resource / nested-resource related helpers extracted
+    # from HttpHelpers to reduce method length and ABC complexity.
+    #
+    # This module provides methods for defining RESTful routes for resources,
+    # handling nested resources, and generating metadata for resource paths
+    # and controller actions.
+    module ResourceHelpers
+      include RubyRoutes::Router::BuildHelpers
+
+      private
+
+      # Define RESTful routes for a resource.
+      #
+      # @param resource_name [Symbol, String] The name of the resource.
+      # @param options [Hash] Options for customizing the resource routes.
+      #   - `:path` [String] Custom path for the resource.
+      #   - `:controller` [String] Custom controller name.
+      #   - `:nested` [Symbol, String] Name of the nested resource.
+      # @param nested_block [Proc] A block for defining nested routes.
+      # @return [void]
+      def define_resource_routes(resource_name, options = {}, &nested_block)
+        meta = resource_meta(resource_name, options)
+        opts = prepare_options(options)
+
+        push_scope(path: "/#{meta[:resource_path]}") do
+          build_routes(opts, meta)
+          handle_nested_option(options, opts)
+          apply_nested_block(nested_block)
+        end
+      end
+
+      # Prepare options by removing the `:to` key if present.
+      #
+      # @param options [Hash] The options hash.
+      # @return [Hash] The prepared options.
+      def prepare_options(options)
+        options.key?(:to) ? options.dup.tap { |h| h.delete(:to) } : options
+      end
+
+      # Build collection and member routes for a resource.
+      #
+      # @param opts [Hash] The options hash.
+      # @param meta [Hash] The resource metadata.
+      # @return [void]
+      def build_routes(opts, meta)
+        build_collection_routes(opts, meta[:to_index], meta[:to_new], meta[:to_create])
+        build_member_routes(opts, meta[:to_show], meta[:to_edit], meta[:to_update], meta[:to_destroy])
+      end
+
+      # Apply a nested block of routes within the scope of a resource.
+      #
+      # @param nested_block [Proc] The block defining nested routes.
+      # @return [void]
+      def apply_nested_block(nested_block)
+        return unless nested_block
+
+        push_scope(path: '/:id') { instance_eval(&nested_block) }
+      end
+
+      # Prepare resource metadata (path/controller/action strings).
+      #
+      # @param resource_name [Symbol, String] The name of the resource.
+      # @param options [Hash] Options for customizing the resource metadata.
+      # @return [Hash] The resource metadata.
+      def resource_meta(resource_name, options)
+        base_name = resource_name.to_s
+        resource_path = options[:path] ? options[:path].to_s : RubyRoutes::Utility::InflectorUtility.pluralize(base_name)
+        controller = options[:controller] || RubyRoutes::Utility::InflectorUtility.pluralize(base_name)
+        build_meta_hash(resource_path, controller)
+      end
+
+      # Build a metadata hash for a resource.
+      #
+      # @param resource_path [String] The resource path.
+      # @param controller [String] The controller name.
+      # @return [Hash] The metadata hash.
+      def build_meta_hash(resource_path, controller)
+        actions = %w[index new create show edit update destroy]
+        meta_hash = actions.each_with_object({}) do |action, hash|
+          hash[:"to_#{action}"] = "#{controller}##{action}"
+        end
+
+        meta_hash.merge(
+          resource_path: resource_path,
+          controller: controller
+        )
+      end
+
+      # Handle the `nested:` shorthand option for resources.
+      #
+      # @param options [Hash] The options hash.
+      # @param opts [Hash] The prepared options hash.
+      # @return [void]
+      def handle_nested_option(options, opts)
+        return unless options[:nested]
+
+        nested_name = options[:nested].to_s
+        nested_path = RubyRoutes::Utility::InflectorUtility.pluralize(nested_name)
+        build_nested_routes(nested_path, opts)
+      end
+
+      # Build nested resource routes.
+      #
+      # @param nested_path [String] The path for the nested resource.
+      # @param opts [Hash] The options hash.
+      # @return [void]
+      def build_nested_routes(nested_path, opts)
+        push_scope(path: '/:id') do
+          push_scope(path: "/#{nested_path}") do
+            add_nested_routes(nested_path, opts)
+          end
+        end
+      end
+
+      # Add routes for a nested resource.
+      #
+      # @param nested_path [String] The path for the nested resource.
+      # @param opts [Hash] The options hash.
+      # @return [void]
+      def add_nested_routes(nested_path, opts)
+        add_route('',                 build_route_options(opts, :get,    "#{nested_path}#index"))
+        add_route('/new',             build_route_options(opts, :get,    "#{nested_path}#new"))
+        add_route('',                 build_route_options(opts, :post,   "#{nested_path}#create"))
+        add_route('/:nested_id',      build_route_options(opts, :get,    "#{nested_path}#show"))
+        add_route('/:nested_id/edit', build_route_options(opts, :get,    "#{nested_path}#edit"))
+        add_route('/:nested_id',      opts.merge(via: %i[put patch], to: "#{nested_path}#update"))
+        add_route('/:nested_id',      build_route_options(opts, :delete, "#{nested_path}#destroy"))
+      end
+    end
+  end
+end

data/lib/ruby_routes/router/scope_helpers.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class Router
+    # ScopeHelpers: encapsulate scope application logic
+    #
+    # This module provides methods for managing and applying scopes in the routing DSL.
+    # Scopes allow you to define nested paths, modules, defaults, and constraints
+    # that apply to a group of routes.
+    module ScopeHelpers
+      private
+
+      # Push a scope onto the scope stack.
+      #
+      # This method temporarily adds a scope entry to the scope stack, executes the
+      # given block, and ensures the scope is removed afterward.
+      #
+      # @param scope_entry [Hash] The scope entry to push onto the stack.
+      # @yield The block to execute within the scope.
+      # @return [void]
+      def push_scope(scope_entry)
+        ensure_unfrozen!
+        return unless block_given?
+
+        @scope_stack.push(scope_entry)
+
+        begin
+          yield
+        ensure
+          @scope_stack.pop
+        end
+      end
+
+      # Apply all scopes to the given path and options.
+      #
+      # This method iterates through the scope stack in reverse order, applying
+      # path, module, defaults, and constraints from each scope to the given path
+      # and options.
+      #
+      # @param path [String] The base path to apply scopes to.
+      # @param options [Hash] The options to apply scopes to.
+      # @return [Hash] The scoped options, including the updated path.
+      def apply_scope(path, options)
+        scoped_options = options.dup
+        scoped_path    = path.to_s.dup
+
+        @scope_stack.reverse_each do |scope|
+          apply_path_scope(scope, scoped_path)
+          apply_module_scope(scope, scoped_options)
+          apply_defaults_scope(scope, scoped_options)
+          apply_constraints_scope(scope, scoped_options)
+        end
+
+        scoped_options[:path] = scoped_path
+        scoped_options
+      end
+
+      # Apply the path from a scope to the given path.
+      #
+      # @param scope [Hash] The scope containing the path.
+      # @param scoped_path [String] The path to prepend the scope's path to.
+      # @return [void]
+      def apply_path_scope(scope, scoped_path)
+        scoped_path.prepend(scope[:path]) if scope[:path]
+      end
+
+      # Apply the module from a scope to the given options.
+      #
+      # This method updates the `:to` or `:controller` option to include the module
+      # from the scope.
+      #
+      # @param scope [Hash] The scope containing the module.
+      # @param scoped_options [Hash] The options to update with the module.
+      # @return [void]
+      def apply_module_scope(scope, scoped_options)
+        return unless scope[:module]
+
+        if scoped_options[:to]
+          controller, action = scoped_options[:to].to_s.split('#', 2)
+          scoped_options[:to] = "#{scope[:module]}/#{controller}##{action}"
+        elsif scoped_options[:controller]
+          scoped_options[:controller].prepend("#{scope[:module]}/")
+        end
+      end
+
+      # Apply the defaults from a scope to the given options.
+      #
+      # @param scope [Hash] The scope containing the defaults.
+      # @param scoped_options [Hash] The options to update with the defaults.
+      # @return [void]
+      def apply_defaults_scope(scope, scoped_options)
+        return unless scope[:defaults]
+
+        scoped_options[:defaults] = (scoped_options[:defaults] || {}).merge(scope[:defaults])
+      end
+
+      # Apply the constraints from a scope to the given options.
+      #
+      # @param scope [Hash] The scope containing the constraints.
+      # @param scoped_options [Hash] The options to update with the constraints.
+      # @return [void]
+      def apply_constraints_scope(scope, scoped_options)
+        return unless scope[:constraints]
+
+        scoped_options[:constraints] = (scoped_options[:constraints] || {}).merge(scope[:constraints])
+      end
+    end
+  end
+end