rage-rb 1.10.1 → 1.12.0

data/lib/rage/controller/api.rb

@@ -11,13 +11,10 @@ class RageController::API
     def __register_action(action)
       raise Rage::Errors::RouterError, "The action '#{action}' could not be found for #{self}" unless method_defined?(action)
 
-      before_actions_chunk = if @__before_actions
-        filtered_before_actions = @__before_actions.select do |h|
-          (!h[:only] || h[:only].include?(action)) &&
-            (!h[:except] || !h[:except].include?(action))
-        end
+      around_actions_total = 0
 
-        lines = filtered_before_actions.map do |h|
+      before_actions_chunk = if @__before_actions
+        lines = __before_actions_for(action).map do |h|
           condition = if h[:if] && h[:unless]
             "if #{h[:if]} && !#{h[:unless]}"
           elsif h[:if]
@@ -26,10 +23,30 @@ class RageController::API
             "unless #{h[:unless]}"
           end
 
-          <<~RUBY
-            #{h[:name]} #{condition}
-            return [@__status, @__headers, @__body] if @__rendered
-          RUBY
+          if h[:around]
+            around_actions_total += 1
+
+            if condition
+              <<~RUBY
+                __should_apply_around_action = #{condition}
+                  !@__before_callback_rendered
+                end
+                #{h[:wrapper]}(__should_apply_around_action) do
+              RUBY
+            else
+              <<~RUBY
+                __should_apply_around_action = !@__before_callback_rendered
+                #{h[:wrapper]}(__should_apply_around_action) do
+              RUBY
+            end
+          else
+            <<~RUBY
+              unless @__before_callback_rendered
+                #{h[:name]} #{condition}
+                @__before_callback_rendered = true if @__rendered
+              end
+            RUBY
+          end
         end
 
         lines.join("\n")
@@ -37,13 +54,10 @@ class RageController::API
         ""
       end
 
-      after_actions_chunk = if @__after_actions
-        filtered_after_actions = @__after_actions.select do |h|
-          (!h[:only] || h[:only].include?(action)) &&
-            (!h[:except] || !h[:except].include?(action))
-        end
+      around_actions_end_chunk = around_actions_total.times.reduce("") { |memo| memo + "end\n" }
 
-        lines = filtered_after_actions.map! do |h|
+      after_actions_chunk = if @__after_actions
+        lines = __after_actions_for(action).map do |h|
           condition = if h[:if] && h[:unless]
             "if #{h[:if]} && !#{h[:unless]}"
           elsif h[:if]
@@ -106,12 +120,15 @@ class RageController::API
 
           #{wrap_parameters_chunk}
           #{before_actions_chunk}
-          #{action}
+          #{action} unless @__before_callback_rendered
+          #{around_actions_end_chunk}
 
           #{if !after_actions_chunk.empty?
             <<~RUBY
-              @__rendered = true
-              #{after_actions_chunk}
+              unless @__before_callback_rendered
+                @__rendered = true
+                #{after_actions_chunk}
+              end
             RUBY
           end}
 
@@ -161,13 +178,29 @@ class RageController::API
     end
 
     # @private
-    @@__tmp_name_seed = ("a".."i").to_a.permutation
+    @@__dynamic_name_seed = ("a".."i").to_a.permutation
+
+    # @private
+    # define a method based on a block
+    def define_dynamic_method(block)
+      name = @@__dynamic_name_seed.next.join
+      define_method("__rage_dynamic_#{name}", block)
+    end
 
     # @private
-    # define temporary method based on a block
-    def define_tmp_method(block)
-      name = @@__tmp_name_seed.next.join
-      define_method("__rage_tmp_#{name}", block)
+    # define a method that will call a specified method if a condition is `true` or yield if `false`
+    def define_maybe_yield(method_name)
+      name = @@__dynamic_name_seed.next.join
+
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def __rage_dynamic_#{name}(condition)
+          if condition
+            #{method_name} { yield }
+          else
+            yield
+          end
+        end
+      RUBY
     end
 
     ############
@@ -193,7 +226,7 @@ class RageController::API
     def rescue_from(*klasses, with: nil, &block)
       unless with
         if block_given?
-          with = define_tmp_method(block)
+          with = define_dynamic_method(block)
         else
           raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
         end
@@ -249,6 +282,39 @@ class RageController::API
       end
     end
 
+    # Register a new `around_action` hook. Calls with the same `action_name` will overwrite the previous ones.
+    #
+    # @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
+    # @option opts [Symbol, Proc] :if only run the callback if the condition is true
+    # @option opts [Symbol, Proc] :unless only run the callback if the condition is false
+    # @example
+    #   around_action :wrap_in_transaction
+    #
+    #   def wrap_in_transaction
+    #     ActiveRecord::Base.transaction do
+    #       yield
+    #     end
+    #   end
+    def around_action(action_name = nil, **opts, &block)
+      action = prepare_action_params(action_name, **opts, &block)
+      action.merge!(around: true, wrapper: define_maybe_yield(action[:name]))
+
+      if @__before_actions && @__before_actions.frozen?
+        @__before_actions = @__before_actions.dup
+      end
+
+      if @__before_actions.nil?
+        @__before_actions = [action]
+      elsif (i = @__before_actions.find_index { |a| a[:name] == action_name })
+        @__before_actions[i] = action
+      else
+        @__before_actions << action
+      end
+    end
+
     # Register a new `after_action` hook. Calls with the same `action_name` will overwrite the previous ones.
     #
     # @param action_name [Symbol, nil] the name of the callback to add
@@ -283,7 +349,7 @@ class RageController::API
     # @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 }
+      i = @__before_actions&.find_index { |a| a[:name] == action_name && !a[:around] }
       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?
@@ -319,12 +385,37 @@ class RageController::API
       @__wrap_parameters_options = { include:, exclude: }
     end
 
+    # @private
+    def __before_action_exists?(name)
+      @__before_actions.any? { |h| h[:name] == name && !h[:around] }
+    end
+
+    # @private
+    def __before_actions_for(action_name)
+      return [] unless @__before_actions
+
+      @__before_actions.select do |h|
+        (!h[:only] || h[:only].include?(action_name)) &&
+          (!h[:except] || !h[:except].include?(action_name))
+      end
+    end
+
+    # @private
+    def __after_actions_for(action_name)
+      return [] unless @__after_actions
+
+      @__after_actions.select do |h|
+        (!h[:only] || h[:only].include?(action_name)) &&
+          (!h[:except] || !h[:except].include?(action_name))
+      end
+    end
+
     private
 
     # used by `before_action` and `after_action`
     def prepare_action_params(action_name = nil, **opts, &block)
       if block_given?
-        action_name = define_tmp_method(block)
+        action_name = define_dynamic_method(block)
       elsif action_name.nil?
         raise ArgumentError, "No handler provided. Pass the `action_name` parameter or provide a block."
       end
@@ -339,8 +430,8 @@ class RageController::API
         unless: _unless
       }
 
-      action[:if] = define_tmp_method(action[:if]) if action[:if].is_a?(Proc)
-      action[:unless] = define_tmp_method(action[:unless]) if action[:unless].is_a?(Proc)
+      action[:if] = define_dynamic_method(action[:if]) if action[:if].is_a?(Proc)
+      action[:unless] = define_dynamic_method(action[:unless]) if action[:unless].is_a?(Proc)
 
       action
     end

data/lib/rage/cookies.rb

@@ -69,7 +69,7 @@ class Rage::Cookies
   # @example
   #   cookies.permanent[:user_id] = current_user.id
   def permanent
-    dup.tap { |c| c.expires = Time.now + 20 * 365 * 24 * 60 * 60 }
+    dup.tap { |c| c.expires = Date.today.next_year(20) }
   end
 
   # Set a cookie.

data/lib/rage/ext/setup.rb

@@ -7,11 +7,13 @@ if defined?(ActiveSupport::IsolatedExecutionState)
   ActiveSupport::IsolatedExecutionState.isolation_level = :fiber
 end
 
-# patch Active Record 6.0 to accept the role argument
-if defined?(ActiveRecord) && ActiveRecord.version < Gem::Version.create("6.1")
+# patch Active Record 6.0 to accept the role argument;
+# for Active Record 6.1 and 7.0 with `legacy_connection_handling == false` this also
+# allows to correctly handle the `:all` argument by ignoring it
+if defined?(ActiveRecord) && ActiveRecord.version < Gem::Version.create("7.1")
   %i(active_connections? connection_pool_list clear_active_connections!).each do |m|
-    ActiveRecord::Base.connection_handler.define_singleton_method(m) do |_ = nil|
-      super()
+    ActiveRecord::Base.connection_handler.define_singleton_method(m) do |role = nil|
+      role == :all ? super() : super(role)
     end
   end
 end

data/lib/rage/openapi/builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+##
+# Build OpenAPI specification for the app. Consists of three steps:
+#
+# * `Rage::OpenAPI::Builder` - build a tree of action nodes;
+# * `Rage::OpenAPI::Parser` - parse OpenAPI tags and save the result into the nodes;
+# * `Rage::OpenAPI::Converter` - convert the tree into an OpenAPI spec;
+#
+class Rage::OpenAPI::Builder
+  class ParsingError < StandardError
+  end
+
+  # @param namespace [String, Module]
+  def initialize(namespace: nil)
+    @namespace = namespace.to_s if namespace
+
+    @collectors_cache = {}
+    @nodes = Rage::OpenAPI::Nodes::Root.new
+    @routes = Rage.__router.routes.group_by { |route| route[:meta][:controller_class] }
+  end
+
+  def run
+    parser = Rage::OpenAPI::Parser.new
+
+    @routes.each do |controller, routes|
+      next if skip_controller?(controller)
+
+      parent_nodes = fetch_ancestors(controller).map do |klass|
+        @nodes.new_parent_node(klass) { |node| parser.parse_dangling_comments(node, parse_class(klass).dangling_comments) }
+      end
+
+      routes.each do |route|
+        action = route[:meta][:action]
+
+        method_comments = fetch_ancestors(controller).filter_map { |klass|
+          parse_class(klass).method_comments(action)
+        }.first
+
+        method_node = @nodes.new_method_node(controller, action, parent_nodes)
+        method_node.http_method, method_node.http_path = route[:method], route[:path]
+
+        parser.parse_method_comments(method_node, method_comments)
+      end
+
+    rescue ParsingError
+      Rage::OpenAPI.__log_warn "skipping #{controller.name} because of parsing error"
+      next
+    end
+
+    Rage::OpenAPI::Converter.new(@nodes).run
+  end
+
+  private
+
+  def skip_controller?(controller)
+    should_skip_controller = controller.nil? || !controller.ancestors.include?(RageController::API)
+    should_skip_controller ||= !controller.name.start_with?(@namespace) if @namespace
+
+    should_skip_controller
+  end
+
+  def fetch_ancestors(controller)
+    controller.ancestors.take_while { |klass| klass != RageController::API }
+  end
+
+  def parse_class(klass)
+    @collectors_cache[klass] ||= begin
+      source_path, _ = Object.const_source_location(klass.name)
+      ast = Prism.parse_file(source_path)
+
+      raise ParsingError if ast.errors.any?
+
+      # save the "comment => file" association
+      ast.comments.each do |comment|
+        comment.location.define_singleton_method(:__source_path) { source_path }
+      end
+
+      collector = Rage::OpenAPI::Collector.new(ast.comments)
+      ast.value.accept(collector)
+
+      collector
+    end
+  end
+end

data/lib/rage/openapi/collector.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+##
+# Collect all global comments or comments attached to methods in a class.
+# At this point we don't care whether these are Rage OpenAPI comments or not.
+#
+class Rage::OpenAPI::Collector < Prism::Visitor
+  # @param comments [Array<Prism::InlineComment>]
+  def initialize(comments)
+    @comments = comments.dup
+    @method_comments = {}
+  end
+
+  def dangling_comments
+    @comments
+  end
+
+  def method_comments(method_name)
+    @method_comments[method_name.to_s]
+  end
+
+  def visit_def_node(node)
+    method_comments = []
+    start_line = node.location.start_line - 1
+
+    loop do
+      comment_i = @comments.find_index { |comment| comment.location.start_line == start_line }
+      if comment_i
+        comment = @comments.delete_at(comment_i)
+        method_comments << comment
+        start_line -= 1
+      end
+
+      break unless comment
+    end
+
+    @method_comments[node.name.to_s] = method_comments.reverse
+
+    # reject comments inside methods
+    @comments.reject! do |comment|
+      comment.location.start_line >= node.location.start_line && comment.location.start_line <= node.location.end_line
+    end
+  end
+end

data/lib/rage/openapi/converter.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Converter
+  # @param nodes [Rage::OpenAPI::Nodes::Root]
+  def initialize(nodes)
+    @nodes = nodes
+    @used_tags = Set.new
+    @used_security_schemes = Set.new
+
+    @spec = {
+      "openapi" => "3.0.0",
+      "info" => {},
+      "components" => {},
+      "tags" => [],
+      "paths" => {}
+    }
+  end
+
+  def run
+    @spec["info"] = {
+      "version" => @nodes.version || "1.0.0",
+      "title" => @nodes.title || build_app_name
+    }
+
+    @spec["paths"] = @nodes.leaves.each_with_object({}) do |node, memo|
+      next if node.private || node.parents.any?(&:private)
+
+      path_parameters = []
+      path = node.http_path.gsub(/:(\w+)/) do
+        path_parameters << $1
+        "{#{$1}}"
+      end
+
+      unless memo.key?(path)
+        memo[path] = {}
+        path_parameters.each do |parameter|
+          (memo[path]["parameters"] ||= []) << {
+            "in" => "path",
+            "name" => parameter,
+            "required" => true,
+            "schema" => { "type" => parameter.end_with?("id") ? "integer" : "string" }
+          }
+        end
+      end
+
+      method = node.http_method.downcase
+      memo[path][method] = {
+        "summary" => node.summary || "",
+        "description" => node.description&.join(" ") || "",
+        "deprecated" => !!(node.deprecated || node.parents.any?(&:deprecated)),
+        "security" => build_security(node),
+        "tags" => build_tags(node)
+      }
+
+      responses = node.parents.reverse.map(&:responses).reduce(&:merge).merge(node.responses)
+
+      memo[path][method]["responses"] = if responses.any?
+        responses.each_with_object({}) do |(status, response), memo|
+          memo[status] = if response.nil?
+            { "description" => "" }
+          elsif response.key?("$ref") && response["$ref"].start_with?("#/components/responses")
+            response
+          else
+            { "description" => "", "content" => { "application/json" => { "schema" => response } } }
+          end
+        end
+      else
+        { "200" => { "description" => "" } }
+      end
+
+      if node.request
+        if node.request.key?("$ref") && node.request["$ref"].start_with?("#/components/requestBodies")
+          memo[path][method]["requestBody"] = node.request
+        else
+          memo[path][method]["requestBody"] = { "content" => { "application/json" => { "schema" => node.request } } }
+        end
+      end
+    end
+
+    if @used_security_schemes.any?
+      @spec["components"]["securitySchemes"] = @used_security_schemes.each_with_object({}) do |auth_entry, memo|
+        memo[auth_entry[:name]] = auth_entry[:definition]
+      end
+    end
+
+    if (shared_components = Rage::OpenAPI.__shared_components["components"])
+      shared_components.each do |definition_type, definitions|
+        (@spec["components"][definition_type] ||= {}).merge!(definitions)
+      end
+    end
+
+    @spec["tags"] = @used_tags.sort.map { |tag| { "name" => tag } }
+
+    @spec
+  end
+
+  private
+
+  def build_app_name
+    basename = Rage.root.basename.to_s
+    basename.capitalize.gsub(/[\s\-_]([a-zA-Z0-9]+)/) { " #{$1.capitalize}" }
+  end
+
+  def build_security(node)
+    available_before_actions = node.controller.__before_actions_for(node.action.to_sym)
+
+    node.auth.filter_map do |auth_entry|
+      if available_before_actions.any? { |action_entry| action_entry[:name] == auth_entry[:method].to_sym }
+        auth_name = auth_entry[:name].gsub(/[^A-Za-z0-9\-._]/, "")
+        @used_security_schemes << auth_entry.merge(name: auth_name)
+
+        { auth_name => [] }
+      end
+    end
+  end
+
+  def build_tags(node)
+    controller_name = node.controller.name.sub(/Controller$/, "")
+    namespace_i = controller_name.rindex("::")
+
+    if namespace_i
+      module_name, class_name = controller_name[0...namespace_i], controller_name[namespace_i + 2..]
+    else
+      module_name, class_name = "", controller_name
+    end
+
+    tag = if module_name =~ /::(V\d+)/
+      "#{$1.downcase}/#{class_name}"
+    else
+      class_name
+    end
+
+    if (custom_tag_resolver = Rage.config.openapi.tag_resolver)
+      tag = custom_tag_resolver.call(node.controller, node.action.to_sym, tag)
+    end
+
+    Array(tag).tap do |node_tags|
+      @used_tags += node_tags
+    end
+  end
+end

data/lib/rage/openapi/index.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="SwaggerUI" />
+    <title>SwaggerUI</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@^5/swagger-ui.css" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@^5/swagger-ui-bundle.js" crossorigin></script>
+    <script>
+      window.onload = () => {
+        window.ui = SwaggerUIBundle({
+          url: '<%= spec_url %>',
+          dom_id: '#swagger-ui',
+        });
+      };
+    </script>
+  </body>
+</html>

data/lib/rage/openapi/nodes/method.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Nodes::Method
+  attr_reader :controller, :action, :parents
+  attr_accessor :http_method, :http_path, :summary, :tag, :deprecated, :private, :description,
+    :request, :responses, :parameters
+
+  # @param controller [RageController::API]
+  # @param action [String]
+  # @param parents [Array<Rage::OpenAPI::Nodes::Parent>]
+  def initialize(controller, action, parents)
+    @controller = controller
+    @action = action
+    @parents = parents
+
+    @responses = {}
+    @parameters = []
+  end
+
+  def root
+    @parents[0].root
+  end
+
+  def auth
+    @parents.flat_map(&:auth)
+  end
+end

data/lib/rage/openapi/nodes/parent.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Nodes::Parent
+  attr_reader :root, :controller
+  attr_accessor :deprecated, :private, :auth, :responses
+
+  # @param root [Rage::OpenAPI::Nodes::Root]
+  # @param controller [RageController::API]
+  def initialize(root, controller)
+    @root = root
+    @controller = controller
+
+    @auth = []
+    @responses = {}
+  end
+end

data/lib/rage/openapi/nodes/root.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+##
+# Represents a tree of method nodes. The tree consists of:
+#
+# * a root node;
+# * method nodes, each of which represents an action in a controller;
+# * parent nodes attached to one or several method nodes;
+#
+# A method node together with its parent nodes represent a complete inheritance chain.
+#
+#                                                 Nodes::Root
+#                                                      |
+#                                     Nodes::Parent<ApplicationController>
+#                                                      |
+#                                      Nodes::Parent<Api::BaseController>
+#                                            /                        \
+#             Nodes::Parent<Api::V1::UsersController>         Nodes::Parent<Api::V2::UsersController>
+#                     /                     \                                     |
+#            Nodes::Method<index>   Nodes::Method<show>                  Nodes::Method<show>
+#
+class Rage::OpenAPI::Nodes::Root
+  attr_reader :leaves
+  attr_accessor :version, :title
+
+  def initialize
+    @parent_nodes_cache = {}
+    @leaves = []
+  end
+
+  # @return [Array<Rage::OpenAPI::Nodes::Parent>]
+  def parent_nodes
+    @parent_nodes_cache.values
+  end
+
+  # @param controller [RageController::API]
+  # @param action [String]
+  # @param parent_nodes [Array<Rage::OpenAPI::Nodes::Parent>]
+  # @return [Rage::OpenAPI::Nodes::Method]
+  def new_method_node(controller, action, parent_nodes)
+    node = Rage::OpenAPI::Nodes::Method.new(controller, action, parent_nodes)
+    @leaves << node
+
+    node
+  end
+
+  # @param controller [RageController::API]
+  # @return [Rage::OpenAPI::Nodes::Parent]
+  def new_parent_node(controller)
+    @parent_nodes_cache[controller] ||= begin
+      node = Rage::OpenAPI::Nodes::Parent.new(self, controller)
+      yield(node)
+      node
+    end
+  end
+end