rage-rb 1.14.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b63589b942c187505390393db5ff827ad647a8ba22b2b6d544f47a0075f73701
-  data.tar.gz: 91cad1e502090ab52bb872ce9216f1deb2cfe150560bf328bb61267a719a5c1c
+  metadata.gz: 537238bd77a6af0c53b59def61a4b94616ca11b8e0bb3f31613d06198c8da2f5
+  data.tar.gz: 4597f16d331862d871aeacf18e701406b825e8208e8d41ec4d29f47d8ce6ce5e
 SHA512:
-  metadata.gz: b0e44e8decbd7b68c8489e6559960585711ea1931ff5cff48622e5303b120bb5920567cf85610faaef7e25fa94d8289ceccaab82ba761ea8c28ded4b436624c6
-  data.tar.gz: 655432e0e793cfa07b744e0adc56f6dc4becd73c9e48d3eb1c4716055849e5c03f1927211d75400a3da97838846329a9520226122635781cbd0f5f6417319687
+  metadata.gz: 7c841546ab6547df2e3846000c2f47089e01d08f8702597df835a4b0d6a9920a9be4a65151e017d59e42c0c922d67887ae4d9403f4a2ae2fb048bddc54520c2a
+  data.tar.gz: '0701518f1f90e2bb6e800272a7054aaec3f401b73002733d4b216febf3758aa2a480a1920d19160779efc7450e6dcd12c0ca97392c6c08a325c6617f39147a0e'

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [1.15.0] - 2025-04-02
+
+### Added
+
+- Enhance the `Rage::Request` class by [@aaoafk](https://github.com/aaoafk) (#123).
+- [OpenAPI] Support the `@param` tag (#134).
+
+### Fixed
+
+- Fix using `Fiber.schedule` in console by [@lkibbalam](https://github.com/lkibbalam) (#143).
+- Correctly handle regexp origins in `Rage::Cors` (#138).
+- [OpenAPI] Correctly handle trailing slash (#141).
+- [OpenAPI] Correctly handle empty shared components (#139).
+- [OpenAPI] Explicitly load Prism (#136).
+- [OpenAPI] Correctly verify available before actions (#144).
+- [OpenAPI] Correctly handle global comments (#140).
+
 ## [1.14.0] - 2025-03-10
 
 ### Added

data/lib/rage/cli.rb

@@ -151,6 +151,7 @@ module Rage
 
       require "irb"
       environment
+      patch_fiber_for_irb
       ARGV.clear
       IRB.start
     end
@@ -235,6 +236,25 @@ module Rage
 
       Rake::Task.tasks.select { |task| !task.comment.nil? && task.name.start_with?("db:") }
     end
+
+    # Override Fiber.schedule for IRB: Enforce sequential execution of fibers in the IRB environment
+    def patch_fiber_for_irb
+      Fiber.class_eval do
+        def self.schedule(&block)
+          fiber = Fiber.new(blocking: true) do
+            Fiber.current.__set_id
+            Fiber.current.__set_result(block.call)
+          end
+          fiber.resume
+
+          fiber
+        end
+
+        def self.await(fibers)
+          Array(fibers).map(&:__get_result)
+        end
+      end
+    end
   end
 
   class CLINewAppGenerator < Thor::Group

data/lib/rage/controller/api.rb

@@ -387,7 +387,7 @@ class RageController::API
 
     # @private
     def __before_action_exists?(name)
-      @__before_actions.any? { |h| h[:name] == name && !h[:around] }
+      @__before_actions&.any? { |h| h[:name] == name && !h[:around] }
     end
 
     # @private

data/lib/rage/errors.rb

@@ -4,4 +4,10 @@ module Rage::Errors
 
   class RouterError < StandardError
   end
+
+  class UnknownHTTPMethod < StandardError
+  end
+
+  class InvalidCustomProxy < StandardError
+  end
 end

data/lib/rage/middleware/cors.rb

@@ -124,7 +124,7 @@ class Rage::Cors
     else
       origins_eval = @origins.map { |origin|
         origin.is_a?(Regexp) ?
-          "origin =~ /#{origin.source}/.freeze" :
+          "origin =~ /#{origin}/.freeze" :
           "origin == '#{origin}'.freeze"
       }.join(" || ")
 

data/lib/rage/openapi/converter.rb

@@ -25,20 +25,23 @@ class Rage::OpenAPI::Converter
     @spec["paths"] = @nodes.leaves.each_with_object({}) do |node, memo|
       next if node.private || node.parents.any?(&:private)
 
-      path_parameters = []
+      path_params = []
       path = node.http_path.gsub(/:(\w+)/) do
-        path_parameters << $1
+        path_params << $1
         "{#{$1}}"
       end
 
       unless memo.key?(path)
         memo[path] = {}
-        path_parameters.each do |parameter|
+        path_params.each do |param|
+          documented_path_param = node.parameters.delete(param)
+
           (memo[path]["parameters"] ||= []) << {
             "in" => "path",
-            "name" => parameter,
+            "name" => param,
             "required" => true,
-            "schema" => { "type" => parameter.end_with?("id") ? "integer" : "string" }
+            "description" => documented_path_param&.dig(:description) || "",
+            "schema" => get_param_type_spec(param, documented_path_param&.dig(:type))
           }
         end
       end
@@ -52,6 +55,10 @@ class Rage::OpenAPI::Converter
         "tags" => build_tags(node)
       }
 
+      if node.parameters.any?
+        memo[path][method]["parameters"] = build_parameters(node)
+      end
+
       responses = node.parents.reverse.map(&:responses).reduce(&:merge).merge(node.responses)
 
       memo[path][method]["responses"] = if responses.any?
@@ -85,7 +92,7 @@ class Rage::OpenAPI::Converter
 
     if (shared_components = Rage::OpenAPI.__shared_components["components"])
       shared_components.each do |definition_type, definitions|
-        (@spec["components"][definition_type] ||= {}).merge!(definitions)
+        (@spec["components"][definition_type] ||= {}).merge!(definitions || {})
       end
     end
 
@@ -101,6 +108,22 @@ class Rage::OpenAPI::Converter
     basename.capitalize.gsub(/[\s\-_]([a-zA-Z0-9]+)/) { " #{$1.capitalize}" }
   end
 
+  def build_parameters(node)
+    node.parameters.map do |param_name, param_info|
+      if param_info.key?(:ref)
+        param_info[:ref]
+      else
+        {
+          "name" => param_name,
+          "in" => "query",
+          "required" => param_info[:required],
+          "description" => param_info[:description] || "",
+          "schema" => get_param_type_spec(param_name, param_info[:type])
+        }
+      end
+    end
+  end
+
   def build_security(node)
     available_before_actions = node.controller.__before_actions_for(node.action.to_sym)
 
@@ -138,4 +161,20 @@ class Rage::OpenAPI::Converter
       @used_tags += node_tags
     end
   end
+
+  def get_param_type_spec(param_name, param_type)
+    unless param_type
+      guessed_type = if param_name == "id" || param_name.end_with?("_id")
+        "Integer"
+      elsif param_name.end_with?("_at")
+        "Time"
+      else
+        "String"
+      end
+
+      return Rage::OpenAPI.__type_to_spec(guessed_type)
+    end
+
+    param_type
+  end
 end

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

@@ -14,7 +14,7 @@ class Rage::OpenAPI::Nodes::Method
     @parents = parents
 
     @responses = {}
-    @parameters = []
+    @parameters = {}
   end
 
   def root

data/lib/rage/openapi/openapi.rb

@@ -4,10 +4,23 @@ require "erb"
 require "yaml"
 
 if !defined?(Prism)
+  begin
+    require "prism"
+  rescue LoadError
+    fail <<~ERR
+
+      Rage::OpenAPI depends on Prism to build OpenAPI specifications. Add the following line to your Gemfile:
+      gem "prism"
+
+    ERR
+  end
+end
+
+if Gem::Version.create(Prism::VERSION) < Gem::Version.create("0.25.0")
   fail <<~ERR
 
-    rage-rb depends on Prism to build OpenAPI specifications. Add the following line to your Gemfile:
-    gem "prism"
+    Rage::OpenAPI is only compatible with Prism >= 0.25.0. Detected Prism version: #{Prism::VERSION}. Add the following line to your Gemfile:
+    gem "prism", ">= 0.25.0"
 
   ERR
 end
@@ -45,7 +58,7 @@ module Rage::OpenAPI
     end
 
     app = ->(env) do
-      if env["PATH_INFO"] == ""
+      if env["PATH_INFO"] == "" || env["PATH_INFO"] == "/"
         html_app.call(env)
       elsif env["PATH_INFO"] == "/json"
         json_app.call(env)
@@ -80,7 +93,7 @@ module Rage::OpenAPI
       else
         case components_file.extname
         when ".yml", ".yaml"
-          YAML.safe_load(components_file.read)
+          YAML.safe_load(components_file.read) || {}
         when ".json"
           JSON.parse(components_file.read)
         else
@@ -117,6 +130,30 @@ module Rage::OpenAPI
     Object
   end
 
+  # @private
+  def self.__type_to_spec(type, default: false)
+    case type
+    when "Integer"
+      { "type" => "integer" }
+    when "Float"
+      { "type" => "number", "format" => "float" }
+    when "Numeric"
+      { "type" => "number" }
+    when "Boolean"
+      { "type" => "boolean" }
+    when "Hash"
+      { "type" => "object" }
+    when "Date"
+      { "type" => "string", "format" => "date" }
+    when "DateTime", "Time"
+      { "type" => "string", "format" => "date-time" }
+    when "String"
+      { "type" => "string" }
+    else
+      { "type" => "string" } if default
+    end
+  end
+
   # @private
   def self.__log_warn(log)
     puts "[OpenAPI] WARNING: #{log}"

data/lib/rage/openapi/parser.rb

@@ -132,6 +132,9 @@ class Rage::OpenAPI::Parser
           end
         end
 
+      elsif expression =~ /@param\s/
+        parse_param_tag(expression, node, comments[i])
+
       elsif expression =~ /@internal\b/
         # no-op
         children = find_children(comments[i + 1..], node)
@@ -162,11 +165,10 @@ class Rage::OpenAPI::Parser
         children << expression.strip
       elsif expression.start_with?("@")
         break
-      elsif !node.summary
-        # no-op - this is likely the summary entry
+      elsif node.is_a?(Rage::OpenAPI::Nodes::Method) && node.summary
+        Rage::OpenAPI.__log_warn "unrecognized expression detected at #{location_msg(comment)}; use two spaces to mark multi-line expressions"
         break
       else
-        Rage::OpenAPI.__log_warn "unrecognized expression detected at #{location_msg(comment)}; use two spaces to mark multi-line expressions"
         break
       end
     end
@@ -208,4 +210,50 @@ class Rage::OpenAPI::Parser
       end
     end
   end
+
+  def parse_param_tag(expression, node, comment)
+    param = expression[7..].strip
+
+    shared_reference_parser = Rage::OpenAPI::Parsers::SharedReference.new
+    if shared_reference_parser.known_definition?(param)
+      if (ref = shared_reference_parser.parse(param))
+        node.parameters[param] = { ref: }
+      else
+        Rage::OpenAPI.__log_warn "invalid shared reference detected at #{location_msg(comment)}"
+      end
+      return
+    end
+
+    param_name, param_type, param_description = param.split(" ", 3)
+    is_required = true
+    param_type_regexp = /^[{\[]\w+[}\]]$/
+
+    if param_type && !param_type&.match?(param_type_regexp)
+      param_description = if param_description
+        "#{param_type} #{param_description}"
+      else
+        param_type
+      end
+
+      param_type = nil
+    end
+
+    if param_name.end_with?("?")
+      param_name = param_name[0...-1]
+      is_required = false
+    end
+
+    if param_type
+      param_type = param_type[1...-1]
+      parsed_param = Rage::OpenAPI.__type_to_spec(param_type)
+    end
+
+    if node.parameters[param_name]
+      Rage::OpenAPI.__log_warn "duplicate `@param` tag detected at #{location_msg(comment)}"
+    elsif param_type && parsed_param.nil?
+      Rage::OpenAPI.__log_warn "unrecognized type `#{param_type}` detected at #{location_msg(comment)}"
+    else
+      node.parameters[param_name] = { type: parsed_param, description: param_description, required: is_required }
+    end
+  end
 end

data/lib/rage/openapi/parsers/ext/alba.rb

@@ -264,22 +264,7 @@ class Rage::OpenAPI::Parsers::Ext::Alba
     end
 
     def get_type_definition(type_id)
-      case type_id
-      when "Integer"
-        { "type" => "integer" }
-      when "Boolean", ":Boolean"
-        { "type" => "boolean" }
-      when "Numeric"
-        { "type" => "number" }
-      when "Float"
-        { "type" => "number", "format" => "float" }
-      when "Date"
-        { "type" => "string", "format" => "date" }
-      when "DateTime", "Time"
-        { "type" => "string", "format" => "date-time" }
-      else
-        { "type" => "string" }
-      end
+      Rage::OpenAPI.__type_to_spec(type_id.delete_prefix(":"), default: true)
     end
   end
 end

data/lib/rage/openapi/parsers/yaml.rb

@@ -42,25 +42,6 @@ class Rage::OpenAPI::Parsers::YAML
   private
 
   def type_to_spec(type)
-    case type
-    when "Integer"
-      { "type" => "integer" }
-    when "Float"
-      { "type" => "number", "format" => "float" }
-    when "Numeric"
-      { "type" => "number" }
-    when "Boolean"
-      { "type" => "boolean" }
-    when "Hash"
-      { "type" => "object" }
-    when "Date"
-      { "type" => "string", "format" => "date" }
-    when "DateTime", "Time"
-      { "type" => "string", "format" => "date-time" }
-    when "String"
-      { "type" => "string" }
-    else
-      { "type" => "string", "enum" => [type] }
-    end
+    Rage::OpenAPI.__type_to_spec(type) || { "type" => "string", "enum" => [type] }
   end
 end

data/lib/rage/request.rb

@@ -1,13 +1,154 @@
 # frozen_string_literal: true
 
 require "time"
+require "set" # required for ruby 3.1
 
 class Rage::Request
+  # @private
+  # regexp to match against a ip address
+  IP_HOST_REGEXP = /\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/
+  # @private
+  # HTTP methods from [RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1](https://www.ietf.org/rfc/rfc2616.txt)
+  RFC2616 = %w(OPTIONS GET HEAD POST PUT DELETE TRACE CONNECT)
+  # @private
+  # HTTP methods from [RFC 2518: HTTP Extensions for Distributed Authoring -- WEBDAV](https://www.ietf.org/rfc/rfc2518.txt)
+  RFC2518 = %w(PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK)
+  # @private
+  # HTTP methods from [RFC 3253: Versioning Extensions to WebDAV](https://www.ietf.org/rfc/rfc3253.txt)
+  RFC3253 = %w(VERSION-CONTROL REPORT CHECKOUT CHECKIN UNCHECKOUT MKWORKSPACE UPDATE LABEL MERGE BASELINE-CONTROL MKACTIVITY)
+  # @private
+  # HTTP methods from [RFC 3648: WebDAV Ordered Collections Protocol](https://www.ietf.org/rfc/rfc3648.txt)
+  RFC3648 = %w(ORDERPATCH)
+  # @private
+  # HTTP methods from [RFC 3744: WebDAV Access Control Protocol](https://www.ietf.org/rfc/rfc3744.txt)
+  RFC3744 = %w(ACL)
+  # @private
+  # HTTP methods from [RFC 5323: WebDAV SEARCH](https://www.ietf.org/rfc/rfc5323.txt)
+  RFC5323 = %w(SEARCH)
+  # @private
+  # HTTP methods from [RFC 4791: Calendaring Extensions to WebDAV](https://www.ietf.org/rfc/rfc4791.txt)
+  RFC4791 = %w(MKCALENDAR)
+  # @private
+  # HTTP methods from [RFC 5789: PATCH Method for HTTP](https://www.ietf.org/rfc/rfc5789.txt)
+  RFC5789 = %w(PATCH)
+
+  # @private
+  # Set data structure of all RFC defined HTTP headers
+  KNOWN_HTTP_METHODS = (RFC2616 + RFC2518 + RFC3253 + RFC3648 + RFC3744 + RFC5323 + RFC4791 + RFC5789).to_set
+
   # @private
   def initialize(env)
     @env = env
   end
 
+  # Check if the request was made using TLS/SSL which is if http or https protocol is used inside the URL.
+  # @return [Boolean] true if the request is TLS/SSL, false otherwise
+  def ssl?
+    rack_request.ssl?
+  end
+
+  # Returns `https://` if this was an HTTPS request and `http://` otherwise.
+  # @return [String] `https://` if this was an HTTP request over SSL/TLS or `http://` if it was an HTTP request
+  def protocol
+    ssl? ? "https://" : "http://"
+  end
+
+  # Get the hostname from the request.
+  # @return [String] the hostname
+  def host
+    rack_request.host
+  end
+
+  # Get the port number from the request.
+  # @return [Integer] the port number
+  def port
+    rack_request.port
+  end
+
+  # Get the query string from the request.
+  # @return [String] the query string (empty string if no query)
+  def query_string
+    rack_request.query_string
+  end
+
+  # Get the Rack environment hash.
+  # @return [Hash] the Rack env
+  def env
+    @env
+  end
+
+  # Check the HTTP request method to see if it was of type `GET`.
+  # @return [Boolean] true if it was a `GET` request
+  def get?
+    rack_request.get?
+  end
+
+  # Check the HTTP request method to see if it was of type `POST`.
+  # @return [Boolean] true if it was a `POST` request
+  def post?
+    rack_request.post?
+  end
+
+  # Check the HTTP request method to see if it was of type `PATCH`.
+  # @return [Boolean] true if it was a `PATCH` request
+  def patch?
+    rack_request.patch?
+  end
+
+  # Check the HTTP request method to see if it was of type `PUT`.
+  # @return [Boolean] true if it was a `PUT` request
+  def put?
+    rack_request.put?
+  end
+
+  # Check the HTTP request method to see if it was of type `DELETE`.
+  # @return [Boolean] true if it was a `DELETE` request
+  def delete?
+    rack_request.delete?
+  end
+
+  # Check the HTTP request method to see if it was of type `HEAD`.
+  # @return [Boolean] true if it was a `HEAD` request
+  def head?
+    rack_request.head?
+  end
+
+  # Get the full request URL.
+  # @return [String] complete URL including protocol, host, path, and query
+  def url
+    rack_request.url
+  end
+
+  # Get the request path.
+  # @return [String] the path component of the URL
+  # @example
+  #   request.path # => "/users"
+  def path
+    rack_request.path
+  end
+
+  # Get the request path including the query string.
+  # @return [String] path with query string (if present)
+  # @example
+  #   request.fullpath # => "/users?show_archived=true"
+  def fullpath
+    rack_request.fullpath
+  end
+
+  # Get the `User-Agent` header value.
+  # @return [String, nil] the user agent string or nil
+  # @example
+  #  request.user_agent # => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
+  def user_agent
+    rack_request.user_agent
+  end
+
+  # Get the content type of the request.
+  # @return [String, nil] the MIME type of the request body
+  def format
+    rack_request.content_type
+  end
+
   # Get the request headers.
   # @example
   #   request.headers["Content-Type"] # => "application/json"
@@ -37,47 +178,26 @@ class Rage::Request
     )
   end
 
-  # Returns the full URL of the request.
-  # @example
-  #   request.url # => "https://example.com/users?show_archived=true"
-  def url
-    scheme = @env["rack.url_scheme"]
-    host = @env["SERVER_NAME"]
-    port = @env["SERVER_PORT"]
-    path = @env["PATH_INFO"]
-    query_string = @env["QUERY_STRING"]
-
-    port_part = (scheme == "http" && port == "80") || (scheme == "https" && port == "443") ? "" : ":#{port}"
-    query_part = query_string.empty? ? "" : "?#{query_string}"
-
-    "#{scheme}://#{host}#{port_part}#{path}#{query_part}"
+  # Get the domain part of the request.
+  # @param tld_length [Integer] top-level domain length
+  # @example Consider a URL like: `example.foo.gov`
+  #   request.domain => "foo.gov"
+  #   request.domain(0) => "gov"
+  #   request.domain(2) => "example.foo.gov"
+  def domain(tld_length = 1)
+    extract_domain(host, tld_length)
   end
 
-  # Returns the path of the request.
-  # @example
-  #   request.path # => "/users"
-  def path
-    @env["PATH_INFO"]
+  # Get the HTTP method of the request. If the client is using the `Rack::MethodOverride`
+  # middleware, then the `X-HTTP-Method-Override` header is checked first.
+  # @return [String] The HTTP Method override header or the request method header
+  def method
+    check_method(@env["rack.methodoverride.original_method"] || @env["REQUEST_METHOD"])
   end
 
-  # Returns the full path including the query string.
-  # @example
-  #   request.fullpath # => "/users?show_archived=true"
-  def fullpath
-    path = @env["PATH_INFO"]
-    query_string = @env["QUERY_STRING"]
-    query_string.empty? ? path : "#{path}?#{query_string}"
-  end
-
-  # Returns the user agent of the request.
-  # @example
-  #  request.user_agent # => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
-  def user_agent
-    @env["HTTP_USER_AGENT"]
-  end
-
-  # Returns the unique request ID. By default, this ID is internally generated, and all log entries created during the request
+  # Get the unique request ID. By default, this ID is internally generated, and all log entries created during the request
   # are tagged with it. Alternatively, you can use the {Rage::RequestId} middleware to derive the ID from the `X-Request-Id` header.
+  # @return [String] the request ID
   def request_id
     @env["rage.request_id"]
   end
@@ -86,6 +206,32 @@ class Rage::Request
 
   private
 
+  def rack_request
+    @rack_request ||= Rack::Request.new(@env)
+  end
+
+  def check_method(name)
+    if name
+      if KNOWN_HTTP_METHODS.include?(name)
+        name
+      else
+        raise(Rage::Errors::UnknownHTTPMethod, "#{name}, accepted HTTP methods are #{KNOWN_HTTP_METHODS.to_a}")
+      end
+    end
+  end
+
+  def extract_domain(host, tld_length)
+    extract_domain_from(host, tld_length) if named_host?(host)
+  end
+
+  def extract_domain_from(host, tld_length)
+    host.split(".").last(1 + tld_length).join(".")
+  end
+
+  def named_host?(host)
+    !IP_HOST_REGEXP.match?(host)
+  end
+
   def if_none_match
     headers["HTTP_IF_NONE_MATCH"]
   end

data/lib/rage/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.14.0
+  version: 1.15.0
 platform: ruby
 authors:
 - Roman Samoilov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor