rage-rb 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04ca7e51d4117d534058db889d82d6ce86af9c9edf389a03711baffa3a8bc484
-  data.tar.gz: 347fa6296d6fa65d99125146b7f82921a9ae2b99836d6f0191fc31dc135896c7
+  metadata.gz: d2f73c4770587ebabc7d8fa0c4793d53742196b928f21cc362799cb068849982
+  data.tar.gz: aecaa4ae2848bc1b15a38da29d3030d718d74697faaf8525e60e82d10b24396c
 SHA512:
-  metadata.gz: 8490a009689d8dbd9c98f47b01701e80dda65fe96dfa991540adc59dc0dd68859690263a15a6cb3f2f2ad23aa300c8bcf4eb6aed468a69b9997191af15806bae
-  data.tar.gz: 7b5d887f78d0d102a9ea92027fe531d61870bed70828a56a4b79c51540c560553dd907c7c27a72867b4adbc241e4e1a4a529b84db991786d6845b457c229bfb2
+  metadata.gz: bb31ef275be5dc22322af8c9d563befc000ad2d15bb22454f2d3664736e6e7881ccdac365e6687fc123c23da1a06ee3cd4d63d08b8b5123c1fee67ebb97fbc57
+  data.tar.gz: 7debadefde85efa180f73e963b252cb1065a6b6f1bf4b8ca6e64e19d82a0ed838d3b321ddf9222006204ab59c3d90213e1a4eb6e1ff04d1d45572c1e166b3d77

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+## [1.13.0] - 2025-02-12
+
+### Added
+
+- [CLI] Support the PORT ENV variable by [@TheBlackArroVV](https://github.com/TheBlackArroVV) (#124).
+- Add the `RequestId` middleware (#127).
+
+### Fixed
+
+- Correctly process persistent HTTP connections (#128).
+- [OpenAPI] Ignore empty comments (#126).
+- [Cable] Improve the time to connect (#129).
+
+## [1.12.0] - 2025-01-21
+
+### Added
+
+- Add Redis adapter (#114).
+- Add global response tags (#110).
+- Implement around_action callbacks (#107).
+
+### Fixed
+
+- Support date types in Alba serializers (#112).
+
 ## [1.11.0] - 2024-12-18
 
 ### Added

data/Gemfile

@@ -15,9 +15,11 @@ group :test do
   gem "http"
   gem "pg"
   gem "mysql2"
+  gem "bigdecimal"
   gem "connection_pool", "~> 2.0"
   gem "rbnacl"
   gem "domain_name"
   gem "websocket-client-simple"
   gem "prism"
+  gem "redis-client"
 end

data/README.md

@@ -6,8 +6,7 @@
 ![Tests](https://github.com/rage-rb/rage/actions/workflows/main.yml/badge.svg)
 ![Ruby Requirement](https://img.shields.io/badge/Ruby-3.1%2B-%23f40000)
 
-
-Inspired by [Deno](https://deno.com) and built on top of [Iodine](https://github.com/rage-rb/iodine), this is a Ruby web framework that is based on the following design principles:
+Rage is a high-performance framework compatible with Rails, featuring [WebSocket](https://github.com/rage-rb/rage/wiki/WebSockets-guide) support and automatic generation of [OpenAPI](https://github.com/rage-rb/rage/wiki/OpenAPI-Guide) documentation for your APIs. The framework is built on top of [Iodine](https://github.com/rage-rb/iodine) and is based on the following design principles:
 
 * **Rails compatible API** - Rails' API is clean, straightforward, and simply makes sense. It was one of the reasons why Rails was so successful in the past.
 

data/lib/rage/all.rb

@@ -30,6 +30,7 @@ require_relative "middleware/origin_validator"
 require_relative "middleware/fiber_wrapper"
 require_relative "middleware/cors"
 require_relative "middleware/reloader"
+require_relative "middleware/request_id"
 
 if defined?(Sidekiq)
   require_relative "sidekiq_session"

data/lib/rage/application.rb

@@ -7,7 +7,7 @@ class Rage::Application
   end
 
   def call(env)
-    init_logger
+    init_logger(env)
 
     handler = @router.lookup(env)
 
@@ -33,9 +33,9 @@ class Rage::Application
   DEFAULT_LOG_CONTEXT = {}.freeze
   private_constant :DEFAULT_LOG_CONTEXT
 
-  def init_logger
+  def init_logger(env)
     Thread.current[:rage_logger] = {
-      tags: [Iodine::Rack::Utils.gen_request_tag],
+      tags: [(env["rage.request_id"] ||= Iodine::Rack::Utils.gen_request_tag)],
       context: DEFAULT_LOG_CONTEXT,
       request_start: Process.clock_gettime(Process::CLOCK_MONOTONIC)
     }

data/lib/rage/cable/adapters/base.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Rage::Cable::Adapters::Base
+  def pick_a_worker(&block)
+    _lock, lock_path = Tempfile.new.yield_self { |file| [file, file.path] }
+
+    Iodine.on_state(:on_start) do
+      if File.new(lock_path).flock(File::LOCK_EX | File::LOCK_NB)
+        if Rage.logger.debug?
+          puts "INFO: #{Process.pid} is managing #{self.class.name.split("::").last} subscriptions."
+        end
+        block.call
+      end
+    end
+  end
+end

data/lib/rage/cable/adapters/redis.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+if !defined?(RedisClient)
+  fail <<~ERR
+
+    Redis adapter depends on the `redis-client` gem. Add the following line to your Gemfile:
+    gem "redis-client"
+
+  ERR
+end
+
+class Rage::Cable::Adapters::Redis < Rage::Cable::Adapters::Base
+  REDIS_STREAM_NAME = "rage:cable:messages"
+  DEFAULT_REDIS_OPTIONS = { reconnect_attempts: [0.05, 0.1, 0.5] }
+  REDIS_MIN_VERSION_SUPPORTED = Gem::Version.create(6)
+
+  def initialize(config)
+    @redis_stream = if (prefix = config.delete(:channel_prefix))
+      "#{prefix}:#{REDIS_STREAM_NAME}"
+    else
+      REDIS_STREAM_NAME
+    end
+
+    @redis_config = RedisClient.config(**DEFAULT_REDIS_OPTIONS.merge(config))
+    @server_uuid = SecureRandom.uuid
+
+    redis_version = get_redis_version
+    if redis_version < REDIS_MIN_VERSION_SUPPORTED
+      raise "Redis adapter only supports Redis 6+. Detected Redis version: #{redis_version}."
+    end
+
+    @trimming_strategy = redis_version < Gem::Version.create("6.2.0") ? :maxlen : :minid
+
+    pick_a_worker { poll }
+  end
+
+  def publish(stream_name, data)
+    message_uuid = SecureRandom.uuid
+
+    publish_redis.call(
+      "XADD",
+      @redis_stream,
+      trimming_method, "~", trimming_value,
+      "*",
+      "1", stream_name,
+      "2", data.to_json,
+      "3", @server_uuid,
+      "4", message_uuid
+    )
+  end
+
+  private
+
+  def publish_redis
+    @publish_redis ||= @redis_config.new_client
+  end
+
+  def trimming_method
+    @trimming_strategy == :maxlen ? "MAXLEN" : "MINID"
+  end
+
+  def trimming_value
+    @trimming_strategy == :maxlen ? "10000" : ((Time.now.to_f - 5 * 60) * 1000).to_i
+  end
+
+  def get_redis_version
+    service_redis = @redis_config.new_client
+    version = service_redis.call("INFO").match(/redis_version:([[:graph:]]+)/)[1]
+
+    Gem::Version.create(version)
+
+  rescue RedisClient::Error => e
+    puts "FATAL: Couldn't connect to Redis - all broadcasts will be limited to the current server."
+    puts e.backtrace.join("\n")
+    REDIS_MIN_VERSION_SUPPORTED
+
+  ensure
+    service_redis.close
+  end
+
+  def error_backoff_intervals
+    @error_backoff_intervals ||= Enumerator.new do |y|
+      y << 0.2 << 0.5 << 1 << 2 << 5
+      loop { y << 10 }
+    end
+  end
+
+  def poll
+    unless Fiber.scheduler
+      Fiber.set_scheduler(Rage::FiberScheduler.new)
+    end
+
+    Iodine.on_state(:start_shutdown) do
+      @stopping = true
+    end
+
+    Fiber.schedule do
+      read_redis = @redis_config.new_client
+      last_id = (Time.now.to_f * 1000).to_i
+      last_message_uuid = nil
+
+      loop do
+        data = read_redis.blocking_call(5, "XREAD", "COUNT", "100", "BLOCK", "5000", "STREAMS", @redis_stream, last_id)
+
+        if data
+          data[@redis_stream].each do |id, (_, stream_name, _, serialized_data, _, broadcaster_uuid, _, message_uuid)|
+            if broadcaster_uuid != @server_uuid && message_uuid != last_message_uuid
+              Rage.config.cable.protocol.broadcast(stream_name, JSON.parse(serialized_data))
+            end
+
+            last_id = id
+            last_message_uuid = message_uuid
+          end
+        end
+
+      rescue RedisClient::Error => e
+        Rage.logger.error("Subscriber error: #{e.message} (#{e.class})")
+        sleep error_backoff_intervals.next
+      rescue => e
+        @stopping ? break : raise(e)
+      else
+        error_backoff_intervals.rewind
+      end
+    end
+  end
+end

data/lib/rage/cable/cable.rb

@@ -8,11 +8,11 @@ module Rage::Cable
   #     run Rage.cable.application
   #   end
   def self.application
-    protocol = Rage.config.cable.protocol
-    protocol.init(__router)
+    # explicitly initialize the adapter
+    __adapter
 
-    handler = __build_handler(protocol)
-    accept_response = [0, protocol.protocol_definition, []]
+    handler = __build_handler(__protocol)
+    accept_response = [0, __protocol.protocol_definition, []]
 
     application = ->(env) do
       if env["rack.upgrade?"] == :websocket
@@ -31,6 +31,15 @@ module Rage::Cable
     @__router ||= Router.new
   end
 
+  # @private
+  def self.__protocol
+    @__protocol ||= Rage.config.cable.protocol.tap { |protocol| protocol.init(__router) }
+  end
+
+  def self.__adapter
+    @__adapter ||= Rage.config.cable.adapter
+  end
+
   # @private
   def self.__build_handler(protocol)
     klass = Class.new do
@@ -42,33 +51,22 @@ module Rage::Cable
         end
 
         @protocol = protocol
+        @default_log_context = {}.freeze
       end
 
       def on_open(connection)
-        Fiber.schedule do
-          @protocol.on_open(connection)
-        rescue => e
-          log_error(e)
-        end
+        connection.env["rage.request_id"] ||= Iodine::Rack::Utils.gen_request_tag
+        schedule_fiber(connection) { @protocol.on_open(connection) }
       end
 
       def on_message(connection, data)
-        Fiber.schedule do
-          @protocol.on_message(connection, data)
-        rescue => e
-          log_error(e)
-        end
+        schedule_fiber(connection) { @protocol.on_message(connection, data) }
       end
 
       if protocol.respond_to?(:on_close)
         def on_close(connection)
           return unless ::Iodine.running?
-
-          Fiber.schedule do
-            @protocol.on_close(connection)
-          rescue => e
-            log_error(e)
-          end
+          schedule_fiber(connection) { @protocol.on_close(connection) }
         end
       end
 
@@ -82,6 +80,15 @@ module Rage::Cable
 
       private
 
+      def schedule_fiber(connection)
+        Fiber.schedule do
+          Thread.current[:rage_logger] = { tags: [connection.env["rage.request_id"]], context: @default_log_context }
+          yield
+        rescue => e
+          log_error(e)
+        end
+      end
+
       def log_error(e)
         Rage.logger.error("Unhandled exception has occured - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
       end
@@ -94,10 +101,14 @@ module Rage::Cable
   #
   # @param stream [String] the name of the stream
   # @param data [Object] the object to send to the clients. This will later be encoded according to the protocol used.
+  # @return [true]
   # @example
   #   Rage.cable.broadcast("chat", { message: "A new member has joined!" })
   def self.broadcast(stream, data)
-    Rage.config.cable.protocol.broadcast(stream, data)
+    __protocol.broadcast(stream, data)
+    __adapter&.publish(stream, data)
+
+    true
   end
 
   # @!parse [ruby]
@@ -120,6 +131,11 @@ module Rage::Cable
   #     end
   #   end
 
+  module Adapters
+    autoload :Base, "rage/cable/adapters/base"
+    autoload :Redis, "rage/cable/adapters/redis"
+  end
+
   module Protocol
   end
 end

data/lib/rage/cable/channel.rb

@@ -418,7 +418,7 @@ class Rage::Cable::Channel
   #     broadcast("notifications", { message: "A new member has joined!" })
   #   end
   def broadcast(stream, data)
-    Rage.config.cable.protocol.broadcast(stream, data)
+    Rage.cable.broadcast(stream, data)
   end
 
   # Transmit data to the current client.

data/lib/rage/cable/protocol/actioncable_v1_json.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "zlib"
+require "set"
+
 ##
 # A protocol defines the structure, rules and semantics for exchanging data between the client and the server.
 # The class that defines a protocol should respond to the following methods:
@@ -17,6 +20,9 @@
 # * `on_shutdown`
 # * `on_close`
 #
+# It is likely that all logic around `@subscription_identifiers` has nothing to do with the protocol itself and
+# should be extracted into another class. We'll refactor this once we start working on a new protocol.
+#
 class Rage::Cable::Protocol::ActioncableV1Json
   module TYPE
     WELCOME = "welcome"
@@ -55,14 +61,30 @@ class Rage::Cable::Protocol::ActioncableV1Json
   def self.init(router)
     @router = router
 
-    ping_counter = Time.now.to_i
-    ::Iodine.run_every(3000) do
-      ping_counter += 1
-      ::Iodine.publish("cable:ping", { type: TYPE::PING, message: ping_counter }.to_json)
+    Iodine.on_state(:on_start) do
+      ping_counter = Time.now.to_i
+
+      Iodine.run_every(3000) do
+        ping_counter += 1
+        Iodine.publish("cable:ping", { type: TYPE::PING, message: ping_counter }.to_json, Iodine::PubSub::PROCESS)
+      end
     end
 
-    # Hash<String(stream name) => Array<Hash>(subscription params)>
-    @subscription_identifiers = Hash.new { |hash, key| hash[key] = [] }
+    # Hash<String(stream name) => Set<Hash>(subscription params)>
+    @subscription_identifiers = Hash.new { |hash, key| hash[key] = Set.new }
+
+    # this is a fallback to synchronize subscription identifiers across different worker processes;
+    # we expect connections to be distributed among all workers, so this code will almost never be called;
+    # we also synchronize subscriptions with the master process so that the forks that are spun up instead
+    # of the crashed ones also had access to the identifiers;
+    Iodine.subscribe("cable:synchronize") do |_, subscription_msg|
+      stream_name, params = Rage::ParamsParser.json_parse(subscription_msg)
+      @subscription_identifiers[stream_name] << params
+    end
+
+    Iodine.on_state(:on_finish) do
+      Iodine.unsubscribe("cable:synchronize")
+    end
   end
 
   # The method is called any time a new WebSocket connection is established.
@@ -147,8 +169,12 @@ class Rage::Cable::Protocol::ActioncableV1Json
   # @param name [String] the stream name
   # @param params [Hash] parameters associated with the client
   def self.subscribe(connection, name, params)
-    connection.subscribe("cable:#{name}:#{params.hash}")
-    @subscription_identifiers[name] << params unless @subscription_identifiers[name].include?(params)
+    connection.subscribe("cable:#{name}:#{Zlib.crc32(params.to_s)}")
+
+    unless @subscription_identifiers[name].include?(params)
+      @subscription_identifiers[name] << params
+      ::Iodine.publish("cable:synchronize", [name, params].to_json)
+    end
   end
 
   # Broadcast data to all clients connected to a stream.
@@ -156,12 +182,8 @@ class Rage::Cable::Protocol::ActioncableV1Json
   # @param name [String] the stream name
   # @param data [Object] the data to send
   def self.broadcast(name, data)
-    i, identifiers = 0, @subscription_identifiers[name]
-
-    while i < identifiers.length
-      params = identifiers[i]
-      ::Iodine.publish("cable:#{name}:#{params.hash}", serialize(params, data))
-      i += 1
+    @subscription_identifiers[name].each do |params|
+      ::Iodine.publish("cable:#{name}:#{Zlib.crc32(params.to_s)}", serialize(params, data))
     end
   end
 end

data/lib/rage/cli.rb

@@ -71,7 +71,7 @@ module Rage
 
       server_options = { service: :http, handler: app }
 
-      server_options[:port] = options[:port] || Rage.config.server.port
+      server_options[:port] = options[:port] || ENV["PORT"] || Rage.config.server.port
       server_options[:address] = options[:binding] || (Rage.env.production? ? "0.0.0.0" : "localhost")
       server_options[:timeout] = Rage.config.server.timeout
       server_options[:max_clients] = Rage.config.server.max_clients

data/lib/rage/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "yaml"
+require "erb"
+
 ##
 # `Rage.configure` can be used to adjust the behavior of your Rage application:
 #
@@ -277,6 +280,30 @@ class Rage::Configuration
         end
       end
     end
+
+    def config
+      @config ||= begin
+        config_file = Rage.root.join("config/cable.yml")
+
+        if config_file.exist?
+          yaml = ERB.new(config_file.read).result
+          YAML.safe_load(yaml, aliases: true, symbolize_names: true)[Rage.env.to_sym] || {}
+        else
+          {}
+        end
+      end
+    end
+
+    def adapter_config
+      config.except(:adapter)
+    end
+
+    def adapter
+      case config[:adapter]
+      when "redis"
+        Rage::Cable::Adapters::Redis.new(adapter_config)
+      end
+    end
   end
 
   class PublicFileServer

data/lib/rage/controller/api.rb

@@ -11,6 +11,8 @@ class RageController::API
     def __register_action(action)
       raise Rage::Errors::RouterError, "The action '#{action}' could not be found for #{self}" unless method_defined?(action)
 
+      around_actions_total = 0
+
       before_actions_chunk = if @__before_actions
         lines = __before_actions_for(action).map do |h|
           condition = if h[:if] && h[:unless]
@@ -21,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")
@@ -32,6 +54,8 @@ class RageController::API
         ""
       end
 
+      around_actions_end_chunk = around_actions_total.times.reduce("") { |memo| memo + "end\n" }
+
       after_actions_chunk = if @__after_actions
         lines = __after_actions_for(action).map do |h|
           condition = if h[:if] && h[:unless]
@@ -96,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}
 
@@ -151,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
 
     ############
@@ -183,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
@@ -239,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
@@ -273,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?
@@ -339,7 +415,7 @@ class RageController::API
     # 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
@@ -354,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
@@ -509,27 +585,27 @@ class RageController::API
 
   if !defined?(::ActionController::Parameters)
     # Get the request data. The keys inside the hash are symbols, so `params.keys` returns an array of `Symbol`.<br>
-    # You can also load Strong Params to have Rage automatically wrap `params` in an instance of `ActionController::Parameters`.<br>
+    # You can also load Strong Parameters to have Rage automatically wrap `params` in an instance of `ActionController::Parameters`.<br>
     # At the same time, if you are not implementing complex filtering rules or working with nested structures, consider using native `Hash#fetch` and `Hash#slice` instead.
     #
     # For multipart file uploads, the uploaded files are represented by an instance of {Rage::UploadedFile}.
     #
     # @return [Hash{Symbol=>String,Array,Hash,Numeric,NilClass,TrueClass,FalseClass}]
-    # @example
-    #   # make sure to load strong params before the `require "rage/all"` call
-    #   require "active_support/all"
-    #   require "action_controller/metal/strong_parameters"
+    # @example With Strong Parameters
+    #   # in the Gemfile:
+    #   gem "activesupport", require: "active_support/all"
+    #   gem "actionpack", require: "action_controller/metal/strong_parameters"
     #
-    #   params.permit(:user).require(:full_name, :dob)
-    # @example
-    #   # without strong params
+    #   # in the controller:
+    #   params.require(:user).permit(:full_name, :dob)
+    # @example Without Strong Parameters
     #   params.fetch(:user).slice(:full_name, :dob)
     def params
       @__params
     end
   else
     def params
-      @params ||= ActionController::Parameters.new(@__params)
+      @__params__ ||= ActionController::Parameters.new(@__params)
     end
   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/fiber_scheduler.rb

@@ -12,10 +12,10 @@ class Rage::FiberScheduler
 
   def io_wait(io, events, timeout = nil)
     f = Fiber.current
-    ::Iodine::Scheduler.attach(io.fileno, events, timeout&.ceil || 0) { |err| f.resume(err) }
+    ::Iodine::Scheduler.attach(io.fileno, events, timeout&.ceil) { |err| f.resume(err) }
 
     err = Fiber.defer(io.fileno)
-    if err && err < 0
+    if err == false || (err && err < 0)
       err
     else
       events

data/lib/rage/middleware/request_id.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+##
+# The middleware establishes a connection between the `X-Request-Id` header (typically generated by a firewall, load balancer, or web server) and
+# Rage's internal logging system. It ensures that:
+#
+# 1. All logs produced during the request are tagged with the value submitted in the `X-Request-Id` header.
+# 2. The request ID is added back to the response in the `X-Request-Id` header. If no `X-Request-Id` header was provided in the request, the middleware adds an internally generated ID to the response.
+#
+# Additionally, the `X-Request-Id` header value is sanitized to a maximum of 255 characters, allowing only alphanumeric characters and dashes.
+#
+# @example
+#   Rage.configure do
+#     config.middleware.use Rage::RequestId
+#   end
+#
+class Rage::RequestId
+  BLACKLISTED_CHARACTERS = /[^\w\-@]/
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    env["rage.request_id"] = validate_external_request_id(env["HTTP_X_REQUEST_ID"])
+    response = @app.call(env)
+    response[1]["X-Request-Id"] = env["rage.request_id"]
+
+    response
+  end
+
+  private
+
+  def validate_external_request_id(request_id)
+    if request_id && !request_id.empty?
+      request_id = request_id[0...255] if request_id.size > 255
+      request_id = request_id.gsub(BLACKLISTED_CHARACTERS, "") if request_id =~ BLACKLISTED_CHARACTERS
+
+      request_id
+    end
+  end
+end

data/lib/rage/openapi/builder.rb

@@ -11,6 +11,7 @@ class Rage::OpenAPI::Builder
   class ParsingError < StandardError
   end
 
+  # @param namespace [String, Module]
   def initialize(namespace: nil)
     @namespace = namespace.to_s if namespace
 

data/lib/rage/openapi/collector.rb

@@ -5,6 +5,7 @@
 # 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 = {}

data/lib/rage/openapi/converter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class Rage::OpenAPI::Converter
+  # @param nodes [Rage::OpenAPI::Nodes::Root]
   def initialize(nodes)
     @nodes = nodes
     @used_tags = Set.new
@@ -51,8 +52,10 @@ class Rage::OpenAPI::Converter
         "tags" => build_tags(node)
       }
 
-      memo[path][method]["responses"] = if node.responses.any?
-        node.responses.each_with_object({}) do |(status, response), memo|
+      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")

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

@@ -5,6 +5,9 @@ class Rage::OpenAPI::Nodes::Method
   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

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

@@ -2,12 +2,15 @@
 
 class Rage::OpenAPI::Nodes::Parent
   attr_reader :root, :controller
-  attr_accessor :deprecated, :private, :auth
+  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

@@ -28,10 +28,15 @@ class Rage::OpenAPI::Nodes::Root
     @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
@@ -39,6 +44,8 @@ class Rage::OpenAPI::Nodes::Root
     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)

data/lib/rage/openapi/openapi.rb

@@ -119,7 +119,7 @@ module Rage::OpenAPI
 
   # @private
   def self.__log_warn(log)
-    puts "WARNING: #{log}"
+    puts "[OpenAPI] WARNING: #{log}"
   end
 
   module Nodes

data/lib/rage/openapi/parser.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 class Rage::OpenAPI::Parser
+  # @param node [Rage::OpenAPI::Nodes::Parent]
+  # @param comments [Array<Prism::InlineComment>]
   def parse_dangling_comments(node, comments)
     i = 0
 
@@ -14,7 +16,7 @@ class Rage::OpenAPI::Parser
         else
           node.deprecated = true
         end
-        children = find_children(comments[i + 1..])
+        children = find_children(comments[i + 1..], node)
 
       elsif expression =~ /@private\b/
         if node.private
@@ -22,7 +24,7 @@ class Rage::OpenAPI::Parser
         else
           node.private = true
         end
-        children = find_children(comments[i + 1..])
+        children = find_children(comments[i + 1..], node)
 
       elsif expression =~ /@version\s/
         if node.root.version
@@ -38,9 +40,12 @@ class Rage::OpenAPI::Parser
           node.root.title = expression[7..]
         end
 
+      elsif expression =~ /@response\s/
+        parse_response_tag(expression, node, comments[i])
+
       elsif expression =~ /@auth\s/
         method, name, tail_name = expression[6..].split(" ", 3)
-        children = find_children(comments[i + 1..])
+        children = find_children(comments[i + 1..], node)
 
         if tail_name
           Rage::OpenAPI.__log_warn "incorrect `@auth` name detected at #{location_msg(comments[i])}; security scheme name cannot contain spaces"
@@ -69,6 +74,8 @@ class Rage::OpenAPI::Parser
     end
   end
 
+  # @param node [Rage::OpenAPI::Nodes::Method]
+  # @param comments [Array<Prism::InlineComment>]
   def parse_method_comments(node, comments)
     i = 0
 
@@ -76,7 +83,9 @@ class Rage::OpenAPI::Parser
       children = nil
       expression = comments[i].slice.delete_prefix("#").strip
 
-      if !expression.start_with?("@")
+      if expression.empty?
+        # no-op
+      elsif !expression.start_with?("@")
         if node.summary
           Rage::OpenAPI.__log_warn "invalid summary entry detected at #{location_msg(comments[i])}; summary should only be one line"
         else
@@ -89,7 +98,7 @@ class Rage::OpenAPI::Parser
         else
           node.deprecated = true
         end
-        children = find_children(comments[i + 1..])
+        children = find_children(comments[i + 1..], node)
 
       elsif expression =~ /@private\b/
         if node.parents.any?(&:private)
@@ -97,38 +106,14 @@ class Rage::OpenAPI::Parser
         else
           node.private = true
         end
-        children = find_children(comments[i + 1..])
+        children = find_children(comments[i + 1..], node)
 
       elsif expression =~ /@description\s/
-        children = find_children(comments[i + 1..])
+        children = find_children(comments[i + 1..], node)
         node.description = [expression[13..]] + children
 
       elsif expression =~ /@response\s/
-        response = expression[10..].strip
-        status, response_data = if response =~ /^\d{3}$/
-          [response, nil]
-        elsif response =~ /^\d{3}/
-          response.split(" ", 2)
-        else
-          ["200", response]
-        end
-
-        if node.responses.has_key?(status)
-          Rage::OpenAPI.__log_warn "duplicate `@response` tag detected at #{location_msg(comments[i])}"
-        elsif response_data.nil?
-          node.responses[status] = nil
-        else
-          parsed = Rage::OpenAPI::Parsers::Response.parse(
-            response_data,
-            namespace: Rage::OpenAPI.__module_parent(node.controller)
-          )
-
-          if parsed
-            node.responses[status] = parsed
-          else
-            Rage::OpenAPI.__log_warn "unrecognized `@response` tag detected at #{location_msg(comments[i])}"
-          end
-        end
+        parse_response_tag(expression, node, comments[i])
 
       elsif expression =~ /@request\s/
         request = expression[9..]
@@ -149,7 +134,7 @@ class Rage::OpenAPI::Parser
 
       elsif expression =~ /@internal\b/
         # no-op
-        children = find_children(comments[i + 1..])
+        children = find_children(comments[i + 1..], node)
 
       else
         Rage::OpenAPI.__log_warn "unrecognized `#{expression.split(" ")[0]}` tag detected at #{location_msg(comments[i])}"
@@ -165,16 +150,21 @@ class Rage::OpenAPI::Parser
 
   private
 
-  def find_children(comments)
+  def find_children(comments, node)
     children = []
 
     comments.each do |comment|
-      expression = comment.slice.sub(/^#\s/, "")
+      expression = comment.slice.sub(/^#\s?/, "")
 
-      if expression.start_with?(/\s{2}/)
+      if expression.empty?
+        # no-op
+      elsif expression.start_with?(/\s{2}/)
         children << expression.strip
       elsif expression.start_with?("@")
         break
+      elsif !node.summary
+        # no-op - this is likely the summary entry
+        break
       else
         Rage::OpenAPI.__log_warn "unrecognized expression detected at #{location_msg(comment)}; use two spaces to mark multi-line expressions"
         break
@@ -190,4 +180,32 @@ class Rage::OpenAPI::Parser
 
     "#{relative_path}:#{location.start_line}"
   end
+
+  def parse_response_tag(expression, node, comment)
+    response = expression[10..].strip
+    status, response_data = if response =~ /^\d{3}$/
+      [response, nil]
+    elsif response =~ /^\d{3}/
+      response.split(" ", 2)
+    else
+      ["200", response]
+    end
+
+    if node.responses.has_key?(status)
+      Rage::OpenAPI.__log_warn "duplicate `@response` tag detected at #{location_msg(comment)}"
+    elsif response_data.nil?
+      node.responses[status] = nil
+    else
+      parsed = Rage::OpenAPI::Parsers::Response.parse(
+        response_data,
+        namespace: Rage::OpenAPI.__module_parent(node.controller)
+      )
+
+      if parsed
+        node.responses[status] = parsed
+      else
+        Rage::OpenAPI.__log_warn "unrecognized `@response` tag detected at #{location_msg(comment)}"
+      end
+    end
+  end
 end

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

@@ -273,6 +273,10 @@ class Rage::OpenAPI::Parsers::Ext::Alba
         { "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

data/lib/rage/request.rb

@@ -76,6 +76,14 @@ class Rage::Request
     @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
+  # are tagged with it. Alternatively, you can use the {Rage::RequestId} middleware to derive the ID from the `X-Request-Id` header.
+  def request_id
+    @env["rage.request_id"]
+  end
+
+  alias_method :uuid, :request_id
+
   private
 
   def if_none_match

data/lib/rage/templates/Gemfile

@@ -1,6 +1,6 @@
 source "https://rubygems.org"
 
-gem "rage-rb", "~> <%= Rage::VERSION[0..2] %>"
+gem "rage-rb", "~> <%= Rage::VERSION.match(/\d+.\d+/).to_s %>"
 
 # Build JSON APIs with ease
 # gem "alba"

data/lib/rage/version.rb

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

data/rage.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "thor", "~> 1.0"
   spec.add_dependency "rack", "~> 2.0"
-  spec.add_dependency "rage-iodine", "~> 4.0"
+  spec.add_dependency "rage-iodine", "~> 4.1"
   spec.add_dependency "zeitwerk", "~> 2.6"
   spec.add_dependency "rack-test", "~> 2.1"
   spec.add_dependency "rake", ">= 12.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Roman Samoilov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-18 00:00:00.000000000 Z
+date: 2025-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -116,6 +116,8 @@ files:
 - lib/rage.rb
 - lib/rage/all.rb
 - lib/rage/application.rb
+- lib/rage/cable/adapters/base.rb
+- lib/rage/cable/adapters/redis.rb
 - lib/rage/cable/cable.rb
 - lib/rage/cable/channel.rb
 - lib/rage/cable/connection.rb
@@ -139,6 +141,7 @@ files:
 - lib/rage/middleware/fiber_wrapper.rb
 - lib/rage/middleware/origin_validator.rb
 - lib/rage/middleware/reloader.rb
+- lib/rage/middleware/request_id.rb
 - lib/rage/openapi/builder.rb
 - lib/rage/openapi/collector.rb
 - lib/rage/openapi/converter.rb