rage-rb 1.10.1 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87a1aecc1f62917581dee82c9efe0d56cebc69046500eeaf7f2e73aa7f35f809
-  data.tar.gz: 6e890b8641f214b2cfbebc2fd56bc1f5a32f2f8c2281cbf8f62d3a607d05c4ad
+  metadata.gz: 04ca7e51d4117d534058db889d82d6ce86af9c9edf389a03711baffa3a8bc484
+  data.tar.gz: 347fa6296d6fa65d99125146b7f82921a9ae2b99836d6f0191fc31dc135896c7
 SHA512:
-  metadata.gz: c659a925cd991c383714d48e803a93edec1703c5e99aacd73d7c4748be00e77ec8077f6c86ec31c13c8fab373c9ef22bc11fec647b0bc233abec710967a827f4
-  data.tar.gz: a0085405ad42e00730128e942b72abf9944f9344d2e9d5b178b393f8f019b517b430a0b3bf3ac7dd8b8e575392e4f79f7c0cc8531093be3d8100a549f13583f2
+  metadata.gz: 8490a009689d8dbd9c98f47b01701e80dda65fe96dfa991540adc59dc0dd68859690263a15a6cb3f2f2ad23aa300c8bcf4eb6aed468a69b9997191af15806bae
+  data.tar.gz: 7b5d887f78d0d102a9ea92027fe531d61870bed70828a56a4b79c51540c560553dd907c7c27a72867b4adbc241e4e1a4a529b84db991786d6845b457c229bfb2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [1.11.0] - 2024-12-18
+
+### Added
+
+- `Rage::OpenAPI` (#109).
+
+### Fixed
+
+- Correctly handle ActiveRecord connections in the environments with `legacy_connection_handling == false` (#108).
+
 ## [1.10.1] - 2024-09-17
 
 ### Fixed

data/Gemfile

@@ -19,4 +19,5 @@ group :test do
   gem "rbnacl"
   gem "domain_name"
   gem "websocket-client-simple"
+  gem "prism"
 end

data/README.md

@@ -46,6 +46,11 @@ Start coding!
 
 This gem is designed to be a drop-in replacement for Rails in API mode. Public API is expected to fully match Rails.
 
+A Rage application can operate in two modes:
+
+* **Rails Mode**: Integrate Rage into an existing Rails application to improve throughput and better handle traffic spikes. For more information, see [Rails Integration](https://github.com/rage-rb/rage/wiki/Rails-integration).
+* **Standalone Mode**: Build high-performance services with minimal setup using Rage. To get started, run `rage new --help` for more details.
+
 Check out in-depth API docs for more information:
 
 - [Controller API](https://rage-rb.pages.dev/RageController/API)

data/lib/rage/code_loader.rb

@@ -37,6 +37,10 @@ class Rage::CodeLoader
     unless Rage.autoload?(:Cable) # the `Cable` component is loaded
       Rage::Cable.__router.reset
     end
+
+    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
+      Rage::OpenAPI.__reset_data_cache
+    end
   end
 
   # in Rails mode - reset the routes; everything else will be done by Rails
@@ -49,6 +53,10 @@ class Rage::CodeLoader
     unless Rage.autoload?(:Cable) # the `Cable` component is loaded
       Rage::Cable.__router.reset
     end
+
+    unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
+      Rage::OpenAPI.__reset_data_cache
+    end
   end
 
   def reloading?

data/lib/rage/configuration.rb

@@ -122,6 +122,17 @@
 #
 # > Allows requests from any origin.
 #
+# # OpenAPI Configuration
+# • _config.openapi.tag_resolver_
+#
+# > Specifies the proc to build tags for API operations. The proc accepts the controller class, the symbol name of the action, and the default tag built by Rage.
+#
+# > ```ruby
+# config.openapi.tag_resolver = proc do |controller, action, default_tag|
+#    # ...
+# end
+# > ```
+#
 # # Transient Settings
 #
 # The settings described in this section should be configured using **environment variables** and are either temporary or will become the default in the future.
@@ -179,6 +190,10 @@ class Rage::Configuration
     @public_file_server ||= PublicFileServer.new
   end
 
+  def openapi
+    @openapi ||= OpenAPI.new
+  end
+
   def internal
     @internal ||= Internal.new
   end
@@ -218,6 +233,10 @@ class Rage::Configuration
       @middlewares = (@middlewares[0..index] + [[new_middleware, args, block]] + @middlewares[index + 1..]).uniq(&:first)
     end
 
+    def include?(middleware)
+      !!find_middleware_index(middleware) rescue false
+    end
+
     private
 
     def find_middleware_index(middleware)
@@ -264,6 +283,10 @@ class Rage::Configuration
     attr_accessor :enabled
   end
 
+  class OpenAPI
+    attr_accessor :tag_resolver
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode

data/lib/rage/controller/api.rb

@@ -12,12 +12,7 @@ class RageController::API
       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
-
-        lines = filtered_before_actions.map do |h|
+        lines = __before_actions_for(action).map do |h|
           condition = if h[:if] && h[:unless]
             "if #{h[:if]} && !#{h[:unless]}"
           elsif h[:if]
@@ -38,12 +33,7 @@ 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
-
-        lines = filtered_after_actions.map! do |h|
+        lines = __after_actions_for(action).map do |h|
           condition = if h[:if] && h[:unless]
             "if #{h[:if]} && !#{h[:unless]}"
           elsif h[:if]
@@ -319,6 +309,31 @@ 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`

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,84 @@
+# 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
+
+  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,43 @@
+# 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
+  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,138 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Converter
+  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)
+      }
+
+      memo[path][method]["responses"] = if node.responses.any?
+        node.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,24 @@
+# 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
+
+  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,13 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Nodes::Parent
+  attr_reader :root, :controller
+  attr_accessor :deprecated, :private, :auth
+
+  def initialize(root, controller)
+    @root = root
+    @controller = controller
+
+    @auth = []
+  end
+end

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

@@ -0,0 +1,49 @@
+# 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
+
+  def parent_nodes
+    @parent_nodes_cache.values
+  end
+
+  def new_method_node(controller, action, parent_nodes)
+    node = Rage::OpenAPI::Nodes::Method.new(controller, action, parent_nodes)
+    @leaves << node
+
+    node
+  end
+
+  def new_parent_node(controller)
+    @parent_nodes_cache[controller] ||= begin
+      node = Rage::OpenAPI::Nodes::Parent.new(self, controller)
+      yield(node)
+      node
+    end
+  end
+end