rage-rb 1.5.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bef8e2aac71af98b85e2946c5ce14a8869126743cc07a023eb5a051606345968
-  data.tar.gz: e9ebad8ddc354ed3d21bc466f5bc24b409c95510c22d8664bf47bfbef90da9d8
+  metadata.gz: 61d3c256494b63668809f556d221c9dd86b1542ce30051c689e1f30a7b1aca00
+  data.tar.gz: 268fc8606e772b06985effe6918270f2ecb1c21b191bfa59ae9a74c0eeb8f459
 SHA512:
-  metadata.gz: 3ab1605a8d6c07c9ab155c3b554ae8e51f17f09f02db1edda13c92916a4cddd4e7539c8d24e4a716253d2638c844324de187d527d4f15c733e4a6a34087f8818
-  data.tar.gz: 3c44ce391e4d9c73f25833437ed3895815c008a4d43c60a933c6c89390e9783366789431d8bb679ca22ee95f879cd6c1bb74bc0b0c853b49975b42272763703b
+  metadata.gz: 0136a9c93cb94dc161367ecac78b3d106404e4450fb1f4c6df8d6e38400da242fdaeebf54a7ed18ae5fc0037bea9e62ae94b5870883a2adb493e5721059a9eb8
+  data.tar.gz: c10509dbc8ae25ae0f1c19b35903664863fb07fb81409fd6cc16b962bde35d46f7bb552562994757b74fcc4d32f6ef9970a66f0893d0c36f11da5c27a7f2b4df

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [1.7.0] - 2024-07-30
+
+### Added
+
+- Support `wrap_parameters` by [@alex-rogachev](https://github.com/alex-rogachev) (#89).
+- Unknown environment error handling by [@cuneyter](https://github.com/cuneyter) (#95).
+- Allow `rescue_from` handlers to not accept arguments (#93).
+
+## [1.6.0] - 2024-07-15
+
+### Added
+
+- Support legacy route helpers (#90).
+- Correctly handle internal Rails routes in `Rage.multi_application` (#91).
+
 ## [1.5.1] - 2024-05-26
 
 ### Fixed

data/Gemfile

@@ -8,12 +8,14 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
-gem "http"
 gem "yard"
+gem "rubocop", "~> 1.65", require: false
 
-gem "pg"
-gem "mysql2"
-gem "connection_pool", "~> 2.0"
-
-gem "rbnacl"
-gem "domain_name"
+group :test do
+  gem "http"
+  gem "pg"
+  gem "mysql2"
+  gem "connection_pool", "~> 2.0"
+  gem "rbnacl"
+  gem "domain_name"
+end

data/OVERVIEW.md

@@ -0,0 +1,53 @@
+### Boot sequence and request lifecycle
+
+The following diagram describes some of Rage's internal components and the way they interact with each other:
+
+![overview](https://github.com/rage-rb/rage/assets/2270393/0d45bbe3-622c-4b17-b8d8-552c567fecb3)
+
+### Executing controller actions
+
+When `Rage::Router::DSL` parses the `config/routes.rb` file and calls the `Rage::Router::Backend` class, it registers actions and stores handler procs.
+
+Consider we have the following controller:
+
+```ruby
+class UsersController < RageController::API
+  before_action :find_user
+  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+
+  def show
+    render json: @user
+  end
+
+  private
+
+  def find_user
+    @user = User.find(params[:id])
+  end
+
+  def render_not_found(_)
+    render status: :not_found
+  end
+end
+```
+
+Before processing requests to `UsersController#show`, Rage has to [register](https://github.com/rage-rb/rage/blob/master/lib/rage/controller/api.rb#L10) the show action. Registering means defining a new method that will look like this:
+
+```ruby
+class UsersController
+  def __run_show
+    find_user
+    show
+  rescue ActiveRecord::RecordNotFound => e
+    render_not_found(e)
+  end
+end
+```
+
+After that, Rage will create and store a handler proc that will look exactly like this:
+
+```ruby
+->(env, params) { UsersController.new(env, params).__run_show }
+```
+
+All of this happens at boot time. Once the request comes in at runtime, Rage will only need to retrieve the handler proc defined earlier and call it.

data/README.md

@@ -15,7 +15,7 @@ Inspired by [Deno](https://deno.com) and built on top of [Iodine](https://github
 
 * **API-only** - separation of concerns is one of the most fundamental principles in software development. Backend and frontend are very different layers with different goals and paths to those goals. Separating BE code from FE code results in a much more sustainable architecture compared with classic Rails monoliths.
 
-* **Acceptance of modern Ruby** - the framework includes a fiber scheduler, which means your code never blocks while waiting on IO.
+* **Acceptance of modern Ruby** - the framework includes a fiber scheduler, which means your code never blocks while waiting on I/O.
 
 ## Installation
 
@@ -116,34 +116,48 @@ class PagesController < RageController::API
 end
 ```
 
-:information_source: **Note**: When using `Fiber.await`, it is important to wrap any instance of IO into a fiber using `Fiber.schedule`.
+:information_source: **Note**: When using `Fiber.await`, it is important to wrap every argument into a fiber using `Fiber.schedule`.
 
 ## Benchmarks
 
-#### hello world
+#### Hello World
 
 ```ruby
-class ArticlesController < ApplicationController
+class BenchmarksController < ApplicationController
   def index
     render json: { hello: "world" }
   end
 end
 ```
-![Requests per second](https://github.com/rage-rb/rage/assets/2270393/6c221903-e265-4c94-80e1-041f266c8f47)
 
-#### waiting on IO
+![Requests per second](https://github.com/user-attachments/assets/a7f864ae-0dfb-4628-a420-265a10d8591d)
+
+#### Waiting on I/O
 
 ```ruby
 require "net/http"
 
-class ArticlesController < ApplicationController
+class BenchmarksController < ApplicationController
   def index
     Net::HTTP.get(URI("<endpoint-that-responds-in-one-second>"))
     head :ok
   end
 end
 ```
-![Time to complete 100 requests](https://github.com/rage-rb/rage/assets/2270393/007044e9-efe0-4675-9cab-8a4868154118)
+
+![Time to complete 100 requests](https://github.com/user-attachments/assets/4f4feda3-bd88-43d8-8999-268534c2f9de)
+
+#### Using ActiveRecord
+
+```ruby
+class BenchmarksController < ApplicationController
+  def show
+    render json: World.find(rand(10_000))
+  end
+end
+```
+
+![Requests per second-2](https://github.com/user-attachments/assets/b7ee0bff-e7c8-4fd4-a565-ce0b67a6320e)
 
 ## Upcoming releases
 

data/lib/rage/cli.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "thor"
 require "rack"
 
@@ -40,7 +41,7 @@ module Rage
       ::Iodine.start
     end
 
-    desc 'routes', 'List all routes.'
+    desc "routes", "List all routes."
     option :grep, aliases: "-g", desc: "Filter routes by pattern"
     option :help, aliases: "-h", desc: "Show this message."
     def routes

data/lib/rage/configuration.rb

@@ -114,7 +114,7 @@ class Rage::Configuration
   def config = self
 
   def log_formatter=(formatter)
-    raise "Custom log formatter should respond to `#call`" unless formatter.respond_to?(:call)
+    raise ArgumentError, "Custom log formatter should respond to `#call`" unless formatter.respond_to?(:call)
     @log_formatter = formatter
   end
 

data/lib/rage/controller/api.rb

@@ -7,6 +7,7 @@ class RageController::API
     # registering means defining a new method which calls the action, makes additional calls (e.g. before actions) and
     # sends a correct response down to the server;
     # returns the name of the newly defined method;
+    # rubocop:disable Layout/IndentationWidth, Layout/EndAlignment, Layout/HeredocIndentation
     def __register_action(action)
       raise Rage::Errors::RouterError, "The action '#{action}' could not be found for #{self}" unless method_defined?(action)
 
@@ -65,7 +66,7 @@ class RageController::API
         lines = @__rescue_handlers.map do |klasses, handler|
           <<~RUBY
           rescue #{klasses.join(", ")} => __e
-            #{handler}(__e)
+            #{instance_method(handler).arity == 0 ? handler : "#{handler}(__e)"}
             [@__status, @__headers, @__body]
           RUBY
         end
@@ -77,7 +78,24 @@ class RageController::API
 
       activerecord_loaded = defined?(::ActiveRecord)
 
-      class_eval <<~RUBY,  __FILE__, __LINE__ + 1
+      wrap_parameters_chunk = if __wrap_parameters_key
+        <<~RUBY
+          wrap_key = self.class.__wrap_parameters_key
+          if !@__params.key?(wrap_key) && @__env["CONTENT_TYPE"]
+            wrap_options = self.class.__wrap_parameters_options
+            wrapped_params = if wrap_options[:include].any?
+                               @__params.slice(*wrap_options[:include])
+                             else
+                               params_to_exclude_by_default = %i[action controller]
+                               @__params.except(*(wrap_options[:exclude] + params_to_exclude_by_default))
+                             end
+
+            @__params[wrap_key] = wrapped_params
+          end
+        RUBY
+      end
+
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
         def __run_#{action}
           #{if activerecord_loaded
             <<~RUBY
@@ -85,6 +103,7 @@ class RageController::API
             RUBY
           end}
 
+          #{wrap_parameters_chunk}
           #{before_actions_chunk}
           #{action}
 
@@ -119,9 +138,11 @@ class RageController::API
         end
       RUBY
     end
+    # rubocop:enable all
 
     # @private
     attr_writer :__before_actions, :__after_actions, :__rescue_handlers
+    attr_accessor :__wrap_parameters_key, :__wrap_parameters_options
 
     # @private
     # pass the variable down to the child; the child will continue to use it until changes need to be made;
@@ -130,6 +151,8 @@ class RageController::API
       klass.__before_actions = @__before_actions.freeze
       klass.__after_actions = @__after_actions.freeze
       klass.__rescue_handlers = @__rescue_handlers.freeze
+      klass.__wrap_parameters_key = __wrap_parameters_key
+      klass.__wrap_parameters_options = __wrap_parameters_options
     end
 
     # @private
@@ -151,24 +174,23 @@ class RageController::API
     # Register a global exception handler. Handlers are inherited and matched from bottom to top.
     #
     # @param klasses [Class, Array<Class>] exception classes to watch on
-    # @param with [Symbol] the name of a handler method. The method must take one argument, which is the raised exception. Alternatively, you can pass a block, which must also take one argument.
+    # @param with [Symbol] the name of a handler method. Alternatively, you can pass a block.
     # @example
     #   rescue_from User::NotAuthorized, with: :deny_access
     #
-    #   def deny_access(exception)
+    #   def deny_access
     #     head :forbidden
     #   end
     # @example
-    #   rescue_from User::NotAuthorized do |_|
-    #     head :forbidden
+    #   rescue_from User::NotAuthorized do |exception|
+    #     render json: { message: exception.message }, status: :forbidden
     #   end
-    # @note Unlike in Rails, the handler must always take an argument. Use `_` if you don't care about the actual exception.
     def rescue_from(*klasses, with: nil, &block)
       unless with
         if block_given?
           with = define_tmp_method(block)
         else
-          raise "No handler provided. Pass the `with` keyword argument or provide a block."
+          raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
         end
       end
 
@@ -183,7 +205,7 @@ class RageController::API
 
     # Register a new `before_action` hook. Calls with the same `action_name` will overwrite the previous ones.
     #
-    # @param action_name [String, nil] the name of the callback to add
+    # @param action_name [Symbol, nil] the name of the callback to add
     # @param [Hash] opts action options
     # @option opts [Symbol, Array<Symbol>] :only restrict the callback to run only for specific actions
     # @option opts [Symbol, Array<Symbol>] :except restrict the callback to run for all actions except specified
@@ -215,7 +237,7 @@ class RageController::API
 
       if @__before_actions.nil?
         @__before_actions = [action]
-      elsif i = @__before_actions.find_index { |a| a[:name] == action_name }
+      elsif (i = @__before_actions.find_index { |a| a[:name] == action_name })
         @__before_actions[i] = action
       else
         @__before_actions << action
@@ -224,7 +246,7 @@ class RageController::API
 
     # Register a new `after_action` hook. Calls with the same `action_name` will overwrite the previous ones.
     #
-    # @param action_name [String, nil] the name of the callback to add
+    # @param action_name [Symbol, nil] the name of the callback to add
     # @param [Hash] opts action options
     # @option opts [Symbol, Array<Symbol>] :only restrict the callback to run only for specific actions
     # @option opts [Symbol, Array<Symbol>] :except restrict the callback to run for all actions except specified
@@ -241,7 +263,7 @@ class RageController::API
 
       if @__after_actions.nil?
         @__after_actions = [action]
-      elsif i = @__after_actions.find_index { |a| a[:name] == action_name }
+      elsif (i = @__after_actions.find_index { |a| a[:name] == action_name })
         @__after_actions[i] = action
       else
         @__after_actions << action
@@ -250,14 +272,14 @@ class RageController::API
 
     # Prevent a `before_action` hook from running.
     #
-    # @param action_name [String] the name of the callback to skip
+    # @param action_name [Symbol] the name of the callback to skip
     # @param only [Symbol, Array<Symbol>] restrict the callback to be skipped only for specific actions
     # @param except [Symbol, Array<Symbol>] restrict the callback to be skipped for all actions except specified
     # @example
     #   skip_before_action :find_photo, only: :create
     def skip_before_action(action_name, only: nil, except: nil)
       i = @__before_actions&.find_index { |a| a[:name] == action_name }
-      raise "The following action was specified to be skipped but couldn't be found: #{self}##{action_name}" unless i
+      raise ArgumentError, "The following action was specified to be skipped but couldn't be found: #{self}##{action_name}" unless i
 
       @__before_actions = @__before_actions.dup if @__before_actions.frozen?
 
@@ -277,6 +299,23 @@ class RageController::API
       @__before_actions[i] = action
     end
 
+    # Initialize controller params wrapping into a nested hash.
+    # If initialized, params wrapping logic will be added to the controller.
+    # Params get wrapped only if the CONTENT_TYPE header is present and params hash doesn't contain a param that
+    # has the same name as the wrapper key.
+    #
+    # @param key [Symbol] key that the wrapped params hash will nested under
+    # @param include [Array] array of params that should be included to the wrapped params hash
+    # @param exclude [Array] array of params that should be excluded from the wrapped params hash
+    # @example
+    #   wrap_parameters :user, include: %i[name age]
+    # @example
+    #   wrap_parameters :user, exclude: %i[address]
+    def wrap_parameters(key, include: [], exclude: [])
+      @__wrap_parameters_key = key
+      @__wrap_parameters_options = { include:, exclude: }
+    end
+
     private
 
     # used by `before_action` and `after_action`
@@ -284,10 +323,10 @@ class RageController::API
       if block_given?
         action_name = define_tmp_method(block)
       elsif action_name.nil?
-        raise "No handler provided. Pass the `action_name` parameter or provide a block."
+        raise ArgumentError, "No handler provided. Pass the `action_name` parameter or provide a block."
       end
 
-       _only, _except, _if, _unless = opts.values_at(:only, :except, :if, :unless)
+      _only, _except, _if, _unless = opts.values_at(:only, :except, :if, :unless)
 
       action = {
         name: action_name,

data/lib/rage/cookies.rb

@@ -97,7 +97,7 @@ class Rage::Cookies
       return
     end
 
-    if domain = value[:domain]
+    if (domain = value[:domain])
       host = @env["HTTP_HOST"]
 
       _domain = if domain.is_a?(String)
@@ -141,7 +141,7 @@ class Rage::Cookies
     return @request_cookies if @parsed
 
     @parsed = true
-    if cookie_header = @env["HTTP_COOKIE"]
+    if (cookie_header = @env["HTTP_COOKIE"])
       cookie_header.split(/; */n).each do |cookie|
         next if cookie.empty?
         key, value = cookie.split("=", 2).yield_self { |k, _| [k.to_sym, _] }
@@ -193,7 +193,7 @@ class Rage::Cookies
           nil
         rescue RbNaCl::CryptoError
           i ||= 0
-          if box = fallback_boxes[i]
+          if (box = fallback_boxes[i])
             i += 1
             retry
           end
@@ -230,10 +230,8 @@ class Rage::Cookies
       end
 
       def fallback_boxes
-        @fallback_boxes ||= begin
-          Rage.config.fallback_secret_key_base.map do |key|
-            RbNaCl::SimpleBox.from_secret_key(RbNaCl::Hash.blake2b(key, digest_size: 32, salt: SALT))
-          end
+        @fallback_boxes ||= Rage.config.fallback_secret_key_base.map do |key|
+          RbNaCl::SimpleBox.from_secret_key(RbNaCl::Hash.blake2b(key, digest_size: 32, salt: SALT))
         end
       end
     end # class << self

data/lib/rage/ext/active_record/connection_pool.rb

@@ -97,7 +97,7 @@ module Rage::Ext::ActiveRecord::ConnectionPool
 
   # Signal that the fiber is finished with the current connection and it can be returned to the pool.
   def release_connection(owner = Fiber.current)
-    if conn = @__in_use.delete(owner)
+    if (conn = @__in_use.delete(owner))
       conn.__idle_since = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       @__connections << conn
       Iodine.publish("ext:ar-connection-released", "", Iodine::PubSub::PROCESS) if @__blocked.length > 0

data/lib/rage/fiber.rb

@@ -2,7 +2,7 @@
 
 ##
 # Rage provides a simple and efficient API to wait on several instances of IO at the same time - {Fiber.await}.
-# 
+#
 # Let's say we have the following controller:
 # ```ruby
 # class UsersController < RageController::API
@@ -34,7 +34,7 @@
 # end
 # ```
 # With this change, if each request takes 1 second to execute, the total execution time will still be 1 second.
-# 
+#
 # ## Creating fibers
 # Many developers see fibers as "lightweight threads" that should be used in conjunction with fiber pools, the same way we use thread pools for threads.<br>
 # Instead, it makes sense to think of fibers as regular Ruby objects. We don't use a pool of arrays when we need to create an array - we create a new object and let Ruby and the GC do their job.<br>
@@ -68,7 +68,7 @@ class Fiber
     @__rage_id = object_id.to_s
   end
 
-   # @private
+  # @private
   def __get_id
     @__rage_id
   end

data/lib/rage/fiber_scheduler.rb

@@ -66,7 +66,7 @@ class Rage::FiberScheduler
   end
 
   # TODO: GC works a little strange with this closure;
-  # 
+  #
   # def timeout_after(duration, exception_class = Timeout::Error, *exception_arguments, &block)
   #   fiber, block_status = Fiber.current, :running
   #   ::Iodine.run_after((duration * 1000).to_i) do

data/lib/rage/logger/json_formatter.rb

@@ -15,7 +15,7 @@ class Rage::JSONFormatter
       context.each { |k, v| context_msg << "\"#{k}\":#{v.to_json}," }
     end
 
-    if final = logger[:final]
+    if (final = logger[:final])
       params, env = final[:params], final[:env]
       if params && params[:controller]
         return "{\"tags\":[\"#{tags[0]}\"],\"timestamp\":\"#{timestamp}\",\"pid\":\"#{@pid}\",\"level\":\"info\",\"method\":\"#{env["REQUEST_METHOD"]}\",\"path\":\"#{env["PATH_INFO"]}\",\"controller\":\"#{Rage::Router::Util.path_to_name(params[:controller])}\",\"action\":\"#{params[:action]}\",#{context_msg}\"status\":#{final[:response][0]},\"duration\":#{final[:duration]}}\n"

data/lib/rage/logger/logger.rb

@@ -8,7 +8,7 @@ require "logger"
 # [fecbba0735355738] timestamp=2023-10-19T11:12:56+00:00 pid=1825 level=info message=hello
 # ```
 # In the log entry above, `timestamp`, `pid`, `level`, and `message` are keys, while `fecbba0735355738` is a tag.
-# 
+#
 # Use {tagged} to add custom tags to an entry:
 # ```ruby
 # Rage.logger.tagged("ApiCall") do

data/lib/rage/logger/text_formatter.rb

@@ -15,7 +15,7 @@ class Rage::TextFormatter
       context.each { |k, v| context_msg << "#{k}=#{v} " }
     end
 
-    if final = logger[:final]
+    if (final = logger[:final])
       params, env = final[:params], final[:env]
       if params && params[:controller]
         return "[#{tags[0]}] timestamp=#{timestamp} pid=#{@pid} level=info method=#{env["REQUEST_METHOD"]} path=#{env["PATH_INFO"]} controller=#{Rage::Router::Util.path_to_name(params[:controller])} action=#{params[:action]} #{context_msg}status=#{final[:response][0]} duration=#{final[:duration]}\n"

data/lib/rage/middleware/cors.rb

@@ -19,7 +19,7 @@ class Rage::Cors
 
     response
   ensure
-    if !$! && origin = @cors_check.call(env)
+    if !$! && (origin = @cors_check.call(env))
       headers = response[1]
       headers["Access-Control-Allow-Origin"] = origin
       if @origins != "*"
@@ -64,7 +64,7 @@ class Rage::Cors
     @methods = if methods != "*"
       methods.map! { |method| method.to_s.upcase }.tap { |m|
         if (invalid_methods = m - @default_methods).any?
-          raise "Unsupported method passed to Rage::Cors: #{invalid_methods[0]}"
+          raise ArgumentError, "Unsupported method passed to Rage::Cors: #{invalid_methods[0]}"
         end
       }.join(", ")
     elsif @allow_credentials
@@ -74,8 +74,8 @@ class Rage::Cors
     end
 
     if @allow_credentials
-      raise "Rage::Cors requires you to explicitly list allowed headers when using `allow_credentials: true`" if @allow_headers == "*"
-      raise "Rage::Cors requires you to explicitly list exposed headers when using `allow_credentials: true`" if @expose_headers == "*"
+      raise ArgumentError, "Rage::Cors requires you to explicitly list allowed headers when using `allow_credentials: true`" if @allow_headers == "*"
+      raise ArgumentError, "Rage::Cors requires you to explicitly list exposed headers when using `allow_credentials: true`" if @expose_headers == "*"
     end
 
     @origins = []
@@ -99,7 +99,7 @@ class Rage::Cors
   def create_headers
     headers = {
       "Access-Control-Allow-Origin" => "",
-      "Access-Control-Allow-Methods" => @methods,
+      "Access-Control-Allow-Methods" => @methods
     }
 
     if @allow_headers

data/lib/rage/middleware/reloader.rb

@@ -8,7 +8,7 @@ class Rage::Reloader
   def call(env)
     Rage.code_loader.reload
     @app.call(env)
-rescue Exception => e
+  rescue Exception => e
     exception_str = "#{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}"
     puts(exception_str)
     [500, {}, [exception_str]]

data/lib/rage/params_parser.rb

@@ -29,7 +29,7 @@ class Rage::ParamsParser
       url_params
     end
 
-  rescue => e
+  rescue
     raise Rage::Errors::BadRequest
   end
 

data/lib/rage/router/backend.rb

@@ -20,7 +20,7 @@ class Rage::Router::Backend
   end
 
   def mount(path, handler, methods)
-    raise "Mount handler should respond to `call`" unless handler.respond_to?(:call)
+    raise ArgumentError, "Mount handler should respond to `call`" unless handler.respond_to?(:call)
 
     raw_handler = handler
     is_sidekiq = handler.respond_to?(:name) && handler.name == "Sidekiq::Web"
@@ -51,8 +51,8 @@ class Rage::Router::Backend
   def on(method, path, handler, constraints: {}, defaults: nil)
     raise "Path could not be empty" if path&.empty?
 
-    if match_index = (path =~ OPTIONAL_PARAM_REGEXP)
-      raise "Optional Parameter has to be the last parameter of the path" if path.length != match_index + $&.length
+    if (match_index = (path =~ OPTIONAL_PARAM_REGEXP))
+      raise ArgumentError, "Optional Parameter has to be the last parameter of the path" if path.length != match_index + $&.length
 
       path_full = path.sub(OPTIONAL_PARAM_REGEXP, "/#{$1}")
       path_optional = path.sub(OPTIONAL_PARAM_REGEXP, "")
@@ -65,7 +65,7 @@ class Rage::Router::Backend
     meta = { raw_handler: handler }
 
     if handler.is_a?(String)
-      raise "Invalid route handler format, expected to match the 'controller#action' pattern" unless handler =~ STRING_HANDLER_REGEXP
+      raise ArgumentError, "Invalid route handler format, expected to match the 'controller#action' pattern" unless handler =~ STRING_HANDLER_REGEXP
 
       controller, action = Rage::Router::Util.path_to_class($1), $2
 
@@ -81,7 +81,7 @@ class Rage::Router::Backend
         handler = ->(_, _) { [404, { "X-Cascade" => "pass" }, []] }
       end
     else
-      raise "Non-string route handler should respond to `call`" unless handler.respond_to?(:call)
+      raise ArgumentError, "Non-string route handler should respond to `call`" unless handler.respond_to?(:call)
       # while regular handlers are expected to be called with the `env` and `params` objects,
       # lambda handlers expect just `env` as an argument;
       # TODO: come up with something nicer?
@@ -189,7 +189,7 @@ class Rage::Router::Backend
         params << "*"
         current_node = current_node.create_wildcard_child
         parent_node_path_index = i + 1
-        raise "Wildcard must be the last character in the route" if i != pattern.length - 1
+        raise ArgumentError, "Wildcard must be the last character in the route" if i != pattern.length - 1
       end
 
       i += 1
@@ -200,12 +200,10 @@ class Rage::Router::Backend
     end
 
     @routes.each do |existing_route|
-      if (
-        existing_route[:method] == method &&
-        existing_route[:pattern] == pattern &&
-        existing_route[:constraints] == constraints
-      )
-        raise "Method '#{method}' already declared for route '#{pattern}' with constraints '#{constraints.inspect}'"
+      if existing_route[:method] == method &&
+         existing_route[:pattern] == pattern &&
+         existing_route[:constraints] == constraints
+        raise ArgumentError, "Method '#{method}' already declared for route '#{pattern}' with constraints '#{constraints.inspect}'"
       end
     end
 

data/lib/rage/router/constrainer.rb

@@ -45,14 +45,14 @@ class Rage::Router::Constrainer
   end
 
   def new_store_for_constraint(constraint)
-    raise "No strategy registered for constraint key '#{constraint}'" unless @strategies[constraint]
+    raise ArgumentError, "No strategy registered for constraint key '#{constraint}'" unless @strategies[constraint]
     @strategies[constraint].storage
   end
 
   def validate_constraints(constraints)
     constraints.each do |key, value|
       strategy = @strategies[key]
-      raise "No strategy registered for constraint key '#{key}'" unless strategy
+      raise ArgumentError, "No strategy registered for constraint key '#{key}'" unless strategy
 
       strategy.validate(value)
     end
@@ -73,7 +73,7 @@ class Rage::Router::Constrainer
         if key == :host
           lines << "   host: env['HTTP_HOST'.freeze],"
         else
-          raise 'unknown non-custom strategy for compiling constraint derivation function'
+          raise ArgumentError, "unknown non-custom strategy for compiling constraint derivation function"
         end
       else
         lines << "  #{strategy.name}: @strategies[#{key}].derive_constraint(env),"

data/lib/rage/router/dsl.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "dsl_plugins/legacy_hash_notation"
+require_relative "dsl_plugins/legacy_root_notation"
+require_relative "dsl_plugins/named_route_helpers"
+require_relative "dsl_plugins/controller_action_options"
+
 class Rage::Router::DSL
   def initialize(router)
     @router = router
@@ -47,6 +52,11 @@ class Rage::Router::DSL
   #     resources :posts
   #   end
   class Handler
+    prepend Rage::Router::DSLPlugins::ControllerActionOptions
+    prepend Rage::Router::DSLPlugins::NamedRouteHelpers
+    prepend Rage::Router::DSLPlugins::LegacyHashNotation
+    prepend Rage::Router::DSLPlugins::LegacyRootNotation
+
     # @private
     def initialize(router)
       @router = router
@@ -67,12 +77,13 @@ class Rage::Router::DSL
     # @param to [String] the route handler in the format of "controller#action"
     # @param constraints [Hash] a hash of constraints for the route
     # @param defaults [Hash] a hash of default parameters for the route
+    # @param on [nil, :member, :collection] a shorthand for wrapping routes in a specific RESTful context
     # @example
     #   get "/photos/:id", to: "photos#show", constraints: { host: /myhost/ }
     # @example
     #   get "/photos(/:id)", to: "photos#show", defaults: { id: "-1" }
-    def get(path, to: nil, constraints: nil, defaults: nil)
-      __on("GET", path, to, constraints, defaults)
+    def get(path, to: nil, constraints: nil, defaults: nil, on: nil)
+      __with_on_scope(on) { __on("GET", path, to, constraints, defaults) }
     end
 
     # Register a new POST route.
@@ -81,12 +92,13 @@ class Rage::Router::DSL
     # @param to [String] the route handler in the format of "controller#action"
     # @param constraints [Hash] a hash of constraints for the route
     # @param defaults [Hash] a hash of default parameters for the route
+    # @param on [nil, :member, :collection] a shorthand for wrapping routes in a specific RESTful context
     # @example
     #   post "/photos", to: "photos#create", constraints: { host: /myhost/ }
     # @example
     #   post "/photos", to: "photos#create", defaults: { format: "jpg" }
-    def post(path, to: nil, constraints: nil, defaults: nil)
-      __on("POST", path, to, constraints, defaults)
+    def post(path, to: nil, constraints: nil, defaults: nil, on: nil)
+      __with_on_scope(on) { __on("POST", path, to, constraints, defaults) }
     end
 
     # Register a new PUT route.
@@ -95,12 +107,13 @@ class Rage::Router::DSL
     # @param to [String] the route handler in the format of "controller#action"
     # @param constraints [Hash] a hash of constraints for the route
     # @param defaults [Hash] a hash of default parameters for the route
+    # @param on [nil, :member, :collection] a shorthand for wrapping routes in a specific RESTful context
     # @example
     #   put "/photos/:id", to: "photos#update", constraints: { host: /myhost/ }
     # @example
     #   put "/photos(/:id)", to: "photos#update", defaults: { id: "-1" }
-    def put(path, to: nil, constraints: nil, defaults: nil)
-      __on("PUT", path, to, constraints, defaults)
+    def put(path, to: nil, constraints: nil, defaults: nil, on: nil)
+      __with_on_scope(on) { __on("PUT", path, to, constraints, defaults) }
     end
 
     # Register a new PATCH route.
@@ -109,12 +122,13 @@ class Rage::Router::DSL
     # @param to [String] the route handler in the format of "controller#action"
     # @param constraints [Hash] a hash of constraints for the route
     # @param defaults [Hash] a hash of default parameters for the route
+    # @param on [nil, :member, :collection] a shorthand for wrapping routes in a specific RESTful context
     # @example
     #   patch "/photos/:id", to: "photos#update", constraints: { host: /myhost/ }
     # @example
     #   patch "/photos(/:id)", to: "photos#update", defaults: { id: "-1" }
-    def patch(path, to: nil, constraints: nil, defaults: nil)
-      __on("PATCH", path, to, constraints, defaults)
+    def patch(path, to: nil, constraints: nil, defaults: nil, on: nil)
+      __with_on_scope(on) { __on("PATCH", path, to, constraints, defaults) }
     end
 
     # Register a new DELETE route.
@@ -123,12 +137,13 @@ class Rage::Router::DSL
     # @param to [String] the route handler in the format of "controller#action"
     # @param constraints [Hash] a hash of constraints for the route
     # @param defaults [Hash] a hash of default parameters for the route
+    # @param on [nil, :member, :collection] a shorthand for wrapping routes in a specific RESTful context
     # @example
     #   delete "/photos/:id", to: "photos#destroy", constraints: { host: /myhost/ }
     # @example
     #   delete "/photos(/:id)", to: "photos#destroy", defaults: { id: "-1" }
-    def delete(path, to: nil, constraints: nil, defaults: nil)
-      __on("DELETE", path, to, constraints, defaults)
+    def delete(path, to: nil, constraints: nil, defaults: nil, on: nil)
+      __with_on_scope(on) { __on("DELETE", path, to, constraints, defaults) }
     end
 
     # Register a new route pointing to '/'.
@@ -198,7 +213,7 @@ class Rage::Router::DSL
       @path_prefixes << path_prefix
       @module_prefixes << module_prefix
 
-      instance_eval &block
+      instance_eval(&block)
 
       @path_prefixes.pop
       @module_prefixes.pop
@@ -207,9 +222,9 @@ class Rage::Router::DSL
     # Scopes a set of routes to the given default options.
     #
     # @param [Hash] opts scope options.
-    # @option opts [String] :module module option
-    # @option opts [String] :path path option
-    # @option opts [String] :controller controller option
+    # @option opts [String] :module the namespace for the controller
+    # @option opts [String] :path the path prefix for the routes
+    # @option opts [String] :controller scopes routes to a specific controller
     # @example Route `/photos` to `Api::PhotosController`
     #   scope module: "api" do
     #     get "photos", to: "photos#index"
@@ -238,7 +253,7 @@ class Rage::Router::DSL
       @module_prefixes << opts[:module] if opts[:module]
       @controllers << opts[:controller] if opts[:controller]
 
-      instance_eval &block
+      instance_eval(&block)
 
       @path_prefixes.pop if opts[:path]
       @module_prefixes.pop if opts[:module]
@@ -254,7 +269,7 @@ class Rage::Router::DSL
     #   end
     def defaults(defaults, &block)
       @defaults << defaults
-      instance_eval &block
+      instance_eval(&block)
       @defaults.pop
     end
 
@@ -267,7 +282,7 @@ class Rage::Router::DSL
     #   end
     def controller(controller, &block)
       @controllers << controller
-      instance_eval &block
+      instance_eval(&block)
       @controllers.pop
     end
 
@@ -282,7 +297,7 @@ class Rage::Router::DSL
     def collection(&block)
       orig_path_prefixes = @path_prefixes
       @path_prefixes = @path_prefixes[0...-1] if @path_prefixes.last&.start_with?(":")
-      instance_eval &block
+      instance_eval(&block)
       @path_prefixes = orig_path_prefixes
     end
 
@@ -302,13 +317,19 @@ class Rage::Router::DSL
         @path_prefixes = [*@path_prefixes[0...-1], ":#{member_prefix}"]
       end
 
-      instance_eval &block
+      instance_eval(&block)
 
       @path_prefixes = orig_path_prefixes
     end
 
     # Automatically create REST routes for a resource.
     #
+    # @param [Hash] opts resource options
+    # @option opts [String] :module the namespace for the controller
+    # @option opts [String] :path the path prefix for the routes
+    # @option opts [Symbol, Array<Symbol>] :only only generate routes for the given actions
+    # @option opts [Symbol, Array<Symbol>] :except generate all routes except for the given actions
+    # @option opts [String] :param overrides the default param name of `:id` in the URL
     # @example Create five REST routes, all mapping to the `Photos` controller:
     #   resources :photos
     #   # GET       /photos       => photos#index
@@ -325,7 +346,7 @@ class Rage::Router::DSL
       end
 
       _module, _path, _only, _except, _param = opts.values_at(:module, :path, :only, :except, :param)
-      raise ":param option can't contain colons" if _param.to_s.include?(":")
+      raise ArgumentError, ":param option can't contain colons" if _param.to_s.include?(":")
 
       _only = Array(_only) if _only
       _except = Array(_except) if _except
@@ -358,17 +379,7 @@ class Rage::Router::DSL
     #   mount Sidekiq::Web => "/sidekiq"
     # @example
     #   mount Sidekiq::Web, at: "/sidekiq", via: :get
-    def mount(*args)
-      if args.first.is_a?(Hash)
-        app = args.first.keys.first
-        at = args.first.values.first
-        via = args[0][:via]
-      else
-        app = args.first
-        at = args[1][:at]
-        via = args[1][:via]
-      end
-
+    def mount(app, at:, via: :all)
       at = "/#{at}" unless at.start_with?("/")
       at = at.delete_suffix("/") if at.end_with?("/")
 
@@ -395,7 +406,7 @@ class Rage::Router::DSL
         if @controllers.any?
           to = "#{@controllers.last}##{path}"
         else
-          raise "Missing :to key on routes definition, please check your routes."
+          raise ArgumentError, "Missing :to key on routes definition, please check your routes."
         end
       end
 
@@ -421,6 +432,19 @@ class Rage::Router::DSL
       end
     end
 
+    def __with_on_scope(on, &block)
+      case on
+      when nil
+        block.call
+      when :member
+        member(&block)
+      when :collection
+        collection(&block)
+      else
+        raise ArgumentError, "Unknown scope :#{on} given to :on"
+      end
+    end
+
     def to_singular(str)
       @active_support_loaded ||= str.respond_to?(:singularize) || :false
       return str.singularize if @active_support_loaded != :false

data/lib/rage/router/dsl_plugins/controller_action_options.rb

@@ -0,0 +1,25 @@
+##
+# Support the `:controller` and `:action` options.
+#
+# @example
+#   get :admins, controller: :users
+# @example
+#   post :search, action: :index
+module Rage::Router::DSLPlugins::ControllerActionOptions
+  %i(get post put patch delete).each do |action_name|
+    define_method(action_name) do |*args, **kwargs|
+      if args.length == 1 && !kwargs.has_key?(:to) && (kwargs.has_key?(:controller) || kwargs.has_key?(:action))
+        path = args[0]
+        controller = kwargs.delete(:controller) || @controllers.last || raise(ArgumentError, "Could not derive the controller value from the route definitions")
+        action = kwargs.delete(:action) || path.split("/").last
+      end
+
+      if controller && action
+        kwargs[:to] = "#{controller}##{action}"
+        super(path, **kwargs)
+      else
+        super(*args, **kwargs)
+      end
+    end
+  end
+end

data/lib/rage/router/dsl_plugins/legacy_hash_notation.rb

@@ -0,0 +1,46 @@
+##
+# Support legacy URL helpers that use hashes instead of the `:to` keyword argument.
+#
+# @example
+#   get "/photos/:id" => "photos#show"
+# @example
+#   mount Sidekiq::Web => "/sidekiq"
+# @example
+#   get "search" => :index
+# @example
+#   get "admin_users" => "users"
+module Rage::Router::DSLPlugins::LegacyHashNotation
+  %i(get post put patch delete).each do |action_name|
+    define_method(action_name) do |*args, **kwargs|
+      if args.empty? && !kwargs.empty?
+        path, handler = kwargs.first
+
+        to = if handler.is_a?(Symbol)
+          raise ArgumentError, "Could not derive the controller value from the route definitions" if @controllers.empty?
+          "#{@controllers.last}##{handler}"
+        elsif handler.is_a?(String) && !handler.include?("#")
+          "#{handler}##{path.split("/").last}"
+        elsif handler.is_a?(String)
+          handler
+        end
+      end
+
+      if path && to
+        options = kwargs.except(path).merge(to: to)
+        super(path, **options)
+      else
+        super(*args, **kwargs)
+      end
+    end
+  end
+
+  def mount(*args, **kwargs)
+    if args.empty? && !kwargs.empty?
+      app, at = kwargs.first
+      options = kwargs.except(app).merge(at: at)
+      super(app, **options)
+    else
+      super
+    end
+  end
+end

data/lib/rage/router/dsl_plugins/legacy_root_notation.rb

@@ -0,0 +1,14 @@
+##
+# Support legacy root helpers that don't use the `:to` keyword argument.
+#
+# @example
+#   root "photos#index"
+module Rage::Router::DSLPlugins::LegacyRootNotation
+  def root(*args, **kwargs)
+    if args.length == 1 && args[0].is_a?(String) && kwargs.empty?
+      super(to: args[0])
+    else
+      super
+    end
+  end
+end

data/lib/rage/router/dsl_plugins/named_route_helpers.rb

@@ -0,0 +1,13 @@
+##
+# Support the `as` option. As Rage currently doesn't generate named route helpers, we simply ignore it.
+#
+# @example
+#   get "/photos/:id", to: "photos#show", as: :user_photos
+module Rage::Router::DSLPlugins::NamedRouteHelpers
+  %i(get post put patch delete).each do |action_name|
+    define_method(action_name) do |*args, **kwargs|
+      kwargs.delete(:as)
+      super(*args, **kwargs)
+    end
+  end
+end

data/lib/rage/router/handler_storage.rb

@@ -35,7 +35,7 @@ class Rage::Router::HandlerStorage
     end
 
     if @handlers.length >= 32
-      raise "Limit reached: a maximum of 32 route handlers per node allowed when there are constraints"
+      raise ArgumentError, "Limit reached: a maximum of 32 route handlers per node allowed when there are constraints"
     end
 
     @handlers << handler_object
@@ -64,7 +64,7 @@ class Rage::Router::HandlerStorage
       end
     end
 
-    eval "->(param_values) { { #{lines.join(',')} } }"
+    eval "->(param_values) { { #{lines.join(",")} } }"
   end
 
   def get_handler_matching_constraints(_derived_constraints)

data/lib/rage/router/strategies/host.rb

@@ -18,7 +18,7 @@ class Rage::Router::Strategies::Host
 
   def validate(value)
     if !value.is_a?(String) && !value.is_a?(Regexp)
-      raise "Host should be a string or a Regexp"
+      raise ArgumentError, "Host should be a string or a Regexp"
     end
   end
 

data/lib/rage/router/util.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Rage::Router::Util
   class << self
     # converts controller name in a path form into a class
@@ -40,9 +42,13 @@ class Rage::Router::Util
 
     def call(env)
       result = @rage_app.call(env)
-      return result if result[0] == :__http_defer__ || result[1]["X-Cascade".freeze] != "pass".freeze
+      return result if result[0] == :__http_defer__
 
-      @rails_app.call(env)
+      if result[1]["X-Cascade"] == "pass" || env["PATH_INFO"].start_with?("/rails/")
+        @rails_app.call(env)
+      else
+        result
+      end
     end
   end
 end

data/lib/rage/setup.rb

@@ -1,6 +1,10 @@
 Iodine.patch_rack
 
-require_relative "#{Rage.root}/config/environments/#{Rage.env}"
+begin
+  require_relative "#{Rage.root}/config/environments/#{Rage.env}"
+rescue LoadError
+  raise LoadError, "The <#{Rage.env}> environment could not be found. Please check the environment name."
+end
 
 # Run application initializers
 Dir["#{Rage.root}/config/initializers/**/*.rb"].each { |initializer| load(initializer) }

data/lib/rage/sidekiq_session.rb

@@ -13,7 +13,7 @@ class Rage::SidekiqSession
   SESSION_KEY = "rage.sidekiq.session"
 
   def self.with_session(env)
-    env["rack.session"] = session = self.new(env)
+    env["rack.session"] = session = new(env)
     response = yield
 
     if session.changed

data/lib/rage/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rage
-  VERSION = "1.5.1"
+  VERSION = "1.7.0"
 end

data/lib/rage-rb.rb

@@ -93,6 +93,9 @@ module Rage
   module Router
     module Strategies
     end
+
+    module DSLPlugins
+    end
   end
 
   module Ext

data/rage.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor .rubocop])
     end
   end
   spec.bindir = "exe"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Roman Samoilov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-26 00:00:00.000000000 Z
+date: 2024-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -94,6 +94,7 @@ files:
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
+- OVERVIEW.md
 - README.md
 - Rakefile
 - exe/rage
@@ -126,6 +127,10 @@ files:
 - lib/rage/router/backend.rb
 - lib/rage/router/constrainer.rb
 - lib/rage/router/dsl.rb
+- lib/rage/router/dsl_plugins/controller_action_options.rb
+- lib/rage/router/dsl_plugins/legacy_hash_notation.rb
+- lib/rage/router/dsl_plugins/legacy_root_notation.rb
+- lib/rage/router/dsl_plugins/named_route_helpers.rb
 - lib/rage/router/handler_storage.rb
 - lib/rage/router/node.rb
 - lib/rage/router/strategies/host.rb