rage-rb 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85fae5bbf87d602fb9cbde9e8356a6bfdb9d8e92ef02380f9124047a8d90d268
-  data.tar.gz: c6ff4ca55836d379609e07dfd9c2025de38aeccc9a29e14803551350f2348652
+  metadata.gz: a2a6374b788898c53131e163a84117c929bc377da2859bfffde070d95b765ae9
+  data.tar.gz: 375203e192cfd682f672e1a618aa801f975898c961ce81a1bfb3ec136807eadf
 SHA512:
-  metadata.gz: 8d81759ffc54e6ede4b079dfed31dda024f274586451951aff72fa02e5cbf1014f31fc5760f07f7817dbf1db78262c88adeaff393020e54cecfd7126c169e0a2
-  data.tar.gz: fe7a3f9d392ed9343609b0c6c4c80624eb85c2df4be31690247355f11df185af2f9fe8ede04dc01583648f0e7cf75724742f2506a38c804618dbfd53c5fb1dde
+  metadata.gz: 4d305b41be71203984c30ff07ce8253befb31b84fbb7c58108983f939dfc5774fb010a4b5d804b2d19e3a4effa9e5b1e755e050ce1453c12a60162d2c48a83fe
+  data.tar.gz: 117a17acc84c35254dbffc60999b325d00a2c333c23962f9805c632913d300d887e65250b418665dca79108ada0a74d8862c41f3d1d4c682b7fcce77bbab7c48

data/ARCHITECTURE.md

@@ -0,0 +1,47 @@
+### Table of Contents
+
+[API Workflow](#api-workflow)<br>
+[Executing Controller Actions](#executing-controller-actions)<br>
+[Cable Workflow](#cable-workflow)<br>
+[OpenAPI Workflow](#openapi-workflow)<br>
+[Design Principles](#design-principles)<br>
+
+### API Workflow
+
+The following diagram describes some of Rage's internal components and the way they interact with each other:
+
+![overview](https://github.com/rage-rb/rage/assets/2270393/0d45bbe3-622c-4b17-b8d8-552c567fecb3)
+
+### Executing Controller Actions
+
+To maximize runtime performance, Rage pre-compiles controller actions when the application boots. For each action, it resolves the full chain of callbacks and exception handlers, building a single, optimized procedure.
+
+When a request comes in, Rage executes this pre-compiled procedure directly, avoiding the overhead of resolving callbacks and exception handlers on every request. All of this happens at boot time to ensure the request-response cycle is as fast as possible.
+
+### Cable Workflow
+
+`Rage::Cable` provides a component for handling real-time communication over WebSockets. The workflow involves authenticating connections and subscribing them to channels for bidirectional messaging.
+
+The following diagram describes the components of a `Rage::Cable` application:
+
+![cable](https://github.com/user-attachments/assets/86db2091-f93a-44f8-9512-c4701770d09e)
+
+### OpenAPI Workflow
+
+`Rage::OpenAPI` generates OpenAPI 3.0 specifications by parsing comments in controller files. This process happens at boot time, building the specification and storing it in memory to be served for API documentation.
+
+The following diagram describes the flow of `Rage::OpenAPI`:
+
+<img width="800" src="https://github.com/user-attachments/assets/b4a87b1e-9a0f-4432-a3e9-0106ff546f3f" />
+
+### Design Principles
+
+* **Lean Happy Path:** We try to execute as many operations as possible during server initialization to minimize workload during request processing. Additionally, new features should be designed to avoid impacting the framework performance for users who do not utilize those features.
+
+* **Performance Over Code Style:** We recognize that framework and application code have different requirements. While testability and readability are crucial for application code, framework code prioritizes performance and careful abstraction. This allows for future modifications while maintaining backward compatibility, though readability remains important.
+
+* **Rails Compatibility:** A key objective is to provide a familiar experience for Rails developers, with the Controller and Cable APIs being largely compatible. However, Rage is not a reimplementation of Rails. Instead, it provides a familiar foundation and builds upon it with its own unique features.
+
+* **Idiomatic Ruby:** We prioritize idiomatic Ruby, avoiding unnecessary abstractions. User-level code is expected to embrace standard Ruby syntax, approaches, and patterns, as this is preferable to a framework-level abstraction that accomplishes the same task.
+
+* **Single-Threaded Fiber-Based Approach:** Each request is processed in a separate, isolated execution context (Fiber), pausing whenever it encounters blocking I/O. The single-threaded approach eliminates thread synchronization overhead, leading to enhanced performance and simplified code.

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [1.18.0] - 2025-10-29
+
+### Added
+
+- Add `Rage::Events` (#167).
+
+### Fixed
+
+- Fix sequential `Fiber.await` calls (#168).
+
+## [1.17.1] - 2025-08-21
+
+### Fixed
+
+- Apply backpressure to every `enqueue` call (#166).
+
 ## [1.17.0] - 2025-08-20
 
 ### Added

data/lib/rage/cli.rb

@@ -12,7 +12,7 @@ module Rage
       File.expand_path("templates", __dir__)
     end
 
-    desc "migration NAME", "Generate a new migration."
+    desc "migration NAME", "Generate a new migration"
     def migration(name = nil)
       return help("migration") if name.nil?
 
@@ -20,7 +20,7 @@ module Rage
       Rake::Task["db:new_migration"].invoke(name)
     end
 
-    desc "model NAME", "Generate a new model."
+    desc "model NAME", "Generate a new model"
     def model(name = nil)
       return help("model") if name.nil?
 
@@ -30,7 +30,7 @@ module Rage
       template("model-template/model.rb", "app/models/#{name.singularize.underscore}.rb")
     end
 
-    desc "controller NAME", "Generate a new controller."
+    desc "controller NAME", "Generate a new controller"
     def controller(name = nil)
       return help("controller") if name.nil?
 
@@ -65,9 +65,9 @@ module Rage
       true
     end
 
-    desc "new PATH", "Create a new application."
-    option :database, aliases: "-d", desc: "Preconfigure for selected database.", enum: %w(mysql trilogy postgresql sqlite3)
-    option :help, aliases: "-h", desc: "Show this message."
+    desc "new PATH", "Create a new application"
+    option :database, aliases: "-d", desc: "Preconfigure for selected database", enum: %w(mysql trilogy postgresql sqlite3)
+    option :help, aliases: "-h", desc: "Show this message"
     def new(path = nil)
       return help("new") if options.help? || path.nil?
 
@@ -75,12 +75,12 @@ module Rage
       CLINewAppGenerator.start([path, options[:database]])
     end
 
-    desc "s", "Start the app server."
-    option :port, aliases: "-p", desc: "Runs Rage on the specified port - defaults to 3000."
-    option :environment, aliases: "-e", desc: "Specifies the environment to run this server under (test/development/production)."
-    option :binding, aliases: "-b", desc: "Binds Rails to the specified IP - defaults to 'localhost' in development and '0.0.0.0' in other environments."
-    option :config, aliases: "-c", desc: "Uses a custom rack configuration."
-    option :help, aliases: "-h", desc: "Show this message."
+    desc "s", "Start the app server"
+    option :port, aliases: "-p", desc: "Runs Rage on the specified port - defaults to 3000"
+    option :environment, aliases: "-e", desc: "Specifies the environment to run this server under (test/development/production)"
+    option :binding, aliases: "-b", desc: "Binds Rails to the specified IP - defaults to 'localhost' in development and '0.0.0.0' in other environments"
+    option :config, aliases: "-c", desc: "Uses a custom rack configuration"
+    option :help, aliases: "-h", desc: "Show this message"
     def server
       return help("server") if options.help?
 
@@ -104,9 +104,9 @@ module Rage
       ::Iodine.start
     end
 
-    desc "routes", "List all routes."
+    desc "routes", "List all routes"
     option :grep, aliases: "-g", desc: "Filter routes by pattern"
-    option :help, aliases: "-h", desc: "Show this message."
+    option :help, aliases: "-h", desc: "Show this message"
     def routes
       return help("routes") if options.help?
       # the result would be something like this:
@@ -162,8 +162,8 @@ module Rage
       end
     end
 
-    desc "c", "Start the app console."
-    option :help, aliases: "-h", desc: "Show this message."
+    desc "c", "Start the app console"
+    option :help, aliases: "-h", desc: "Show this message"
     def console
       return help("console") if options.help?
 
@@ -185,17 +185,49 @@ module Rage
       end
     end
 
+    desc "events [EVENT1, EVENT2]", "List all registered events and their subscribers"
+    option :help, aliases: "-h", desc: "Show this message"
+    def events(*event_class_names)
+      return help("events") if options.help?
+
+      environment
+      Rage::Events.__eager_load_subscribers if Rage.env.development?
+
+      event_classes = if event_class_names.any?
+        event_class_names.flat_map { |name| name.split(",") }.map do |event_class_name|
+          @last_event_class_name = event_class_name
+          Object.const_get(event_class_name)
+        end
+      else
+        registered_events = Rage::Events.__registered_subscribers.keys
+        registered_events.reject do |event_class|
+          registered_events.any? { |e| e.ancestors.include?(event_class) && e.ancestors.index(event_class) != 0 }
+        end
+      end
+
+      event_classes.each { |event_class| print_event_subscribers_tree(event_class) }
+
+    rescue NameError
+      if @last_event_class_name
+        spell_checker = DidYouMean::SpellChecker.new(dictionary: Rage::Events.__registered_subscribers.keys)
+        suggestion = DidYouMean.formatter.message_for(spell_checker.correct(@last_event_class_name))
+        puts "Could not find the `#{@last_event_class_name}` event. #{suggestion}"
+      else
+        raise
+      end
+    end
+
     desc "version", "Return the current version of the framework"
     def version
       puts Rage::VERSION
     end
 
     map "generate" => :g
-    desc "g TYPE", "Generate new code."
+    desc "g TYPE", "Generate new code"
     subcommand "g", CLICodeGenerator
 
     map "--tasks" => :tasks
-    desc "--tasks", "See the list of available tasks."
+    desc "--tasks", "See the list of available tasks"
     def tasks
       require "io/console"
 
@@ -275,6 +307,57 @@ module Rage
         end
       end
     end
+
+    def print_event_subscribers_tree(event_class)
+      subscribers = Rage::Events.__get_subscribers(event_class)
+
+      event_ancestors = event_class.ancestors.take_while { |klass| klass != Struct && klass != Data && klass != Object }
+
+      # build a tree of all events and their subscribers
+      tree = event_ancestors.each_with_object({}) do |ancestor, memo|
+        level = event_class.ancestors.count { |klass| klass.ancestors.include?(ancestor) } - 1
+        filtered_subscribers = subscribers.select { |subscriber| subscriber.__event_classes.include?(ancestor) }
+
+        memo[ancestor] = { level:, subscribers: filtered_subscribers }
+      end
+
+      # reject events without subscribers located on the last levels
+      i = 0
+      tree = tree.reject do |_, node|
+        level, subscribers = node[:level], node[:subscribers]
+        next_level = tree.values.dig(i + 1, :level)
+        i += 1
+
+        (next_level.nil? || next_level < level) && subscribers.empty?
+      end
+
+      # indentation for each level
+      padding = " " * 3
+
+      # print the tree
+      tree.each_with_index do |(event_ancestor, node), i|
+        level, subscribers = node[:level], node[:subscribers]
+        next_level = tree.values.dig(i + 1, :level)
+
+        prefix = if i > 0 && next_level != level
+          "└─"
+        else
+          "├─"
+        end
+
+        event_class_line = "#{padding * level}#{prefix} \e[90m#{event_ancestor}\e[0m"
+        if level == 0
+          puts event_class_line
+        else
+          puts "|#{event_class_line}"
+        end
+
+        subscribers.each do |subscriber|
+          prefix = subscriber == subscribers.last && next_level != level + 1 ? "└─" : "├─"
+          puts "│#{padding * (level + 1)}#{prefix} \e[1m#{subscriber}\e[0m"
+        end
+      end
+    end
   end
 
   class CLINewAppGenerator < Thor::Group

data/lib/rage/code_loader.rb

@@ -64,6 +64,10 @@ class Rage::CodeLoader
     @last_watched, @last_update_at = current_watched, current_update_at
   end
 
+  def load_file(path)
+    @loader.load_file(path)
+  end
+
   private
 
   def configure_components
@@ -83,5 +87,9 @@ class Rage::CodeLoader
     unless Rage.autoload?(:OpenAPI) # the `OpenAPI` component is loaded
       Rage::OpenAPI.__reset_data_cache
     end
+
+    unless Rage.autoload?(:Events) # the `Events` component is loaded
+      Rage::Events.__reset_subscribers
+    end
   end
 end

data/lib/rage/configuration.rb

@@ -164,7 +164,7 @@ require "erb"
 # > Enables the backpressure for deferred tasks. The backpressure is used to limit the number of pending tasks in the queue. It accepts a hash with the following options:
 # >
 # > - `:high_water_mark` - the maximum number of pending tasks in the queue. Defaults to `1000`.
-# > - `:low_water_mark` - the minimum number of pending tasks in the queue before the backpressure is released. Defaults to `800`.
+# > - `:low_water_mark` - the minimum number of pending tasks in the queue before the backpressure is released. Defaults to `high_water_mark * 0.8`.
 # > - `:timeout` - the timeout for the backpressure in seconds. Defaults to `2`.
 #
 # > ```ruby
@@ -443,7 +443,7 @@ class Rage::Configuration
         return
       end
 
-      if opts.except(:high_water_mark, :low_water_mark, :timeout).any?
+      if config.except(:high_water_mark, :low_water_mark, :timeout).any?
         raise ArgumentError, "unsupported backpressure options; supported keys are `:high_water_mark`, `:low_water_mark`, `:timeout`"
       end
 
@@ -502,6 +502,14 @@ class Rage::Configuration
   class Internal
     attr_accessor :rails_mode
 
+    def initialized!
+      @initialized = true
+    end
+
+    def initialized?
+      !!@initialized
+    end
+
     def patch_ar_pool?
       !ENV["RAGE_DISABLE_AR_POOL_PATCH"] && !Rage.env.test?
     end

data/lib/rage/deferred/deferred.rb

@@ -79,6 +79,10 @@ module Rage::Deferred
 
   class PushTimeout < StandardError
   end
+
+  # @private
+  class TaskFailed < StandardError
+  end
 end
 
 require_relative "task"

data/lib/rage/deferred/queue.rb

@@ -61,9 +61,7 @@ class Rage::Deferred::Queue
   private
 
   def apply_backpressure
-    if @backlog_size > @backpressure.high_water_mark && !Fiber[:rage_backpressure_applied]
-      Fiber[:rage_backpressure_applied] = true
-
+    if @backlog_size > @backpressure.high_water_mark
       i, target_backlog_size = 0, @backpressure.low_water_mark
       while @backlog_size > target_backlog_size && i < @backpressure.timeout_iterations
         sleep @backpressure.sleep_interval

data/lib/rage/deferred/task.rb

@@ -63,6 +63,8 @@ module Rage::Deferred::Task
       __with_optional_log_tag(request_id) do
         perform(*args, **kwargs)
         true
+      rescue Rage::Deferred::TaskFailed
+        false
       rescue Exception => e
         Rage.logger.error("Deferred task failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
         false

data/lib/rage/events/events.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+##
+# `Rage::Events` provides a lightweight event-driven system for publishing and subscribing to events.
+# Define events as data structures, register subscriber classes, and publish events to notify all relevant subscribers.
+# Subscribers can process events and optionally receive additional context with each event.
+#
+# Define an event:
+# ```ruby
+# UserRegistered = Data.define(:user_id)
+# ```
+#
+# Define a subscriber:
+# ```ruby
+# class SendWelcomeEmail
+#   include Rage::Events::Subscriber
+#   subscribe_to UserRegistered
+#
+#   def call(event)
+#     puts "Sending welcome email to user #{event.user_id}"
+#   end
+# end
+# ```
+#
+# Publish an event:
+# ```ruby
+# Rage::Events.publish(UserRegistered.new(user_id: 1))
+# ```
+#
+module Rage::Events
+  # Publish an event to all subscribers registered for the event's class or its ancestors.
+  # Optionally, additional context data can be provided and passed to each subscriber.
+  #
+  # @param event [Object] the event to publish
+  # @param context [Object] additional data to publish along with the event
+  # @example Publish an event
+  #   Rage::Events.publish(MyEvent.new)
+  # @example Publish an event with context
+  #   Rage::Events.publish(MyEvent.new, context: { published_at: Time.now })
+  def self.publish(event, context: nil)
+    handler = __event_handlers[event.class] || __build_event_handler(event.class)
+    handler.call(event, context)
+
+    nil
+  end
+
+  # @private
+  def self.__registered_subscribers
+    @__registered_subscribers ||= Hash.new { |hash, key| hash[key] = [] }
+  end
+
+  # @private
+  def self.__register_subscriber(event_class, handler_class)
+    __registered_subscribers[event_class] << handler_class
+  end
+
+  # @private
+  def self.__get_subscribers(event_class)
+    event_class.ancestors.take_while { |klass|
+      klass != Object && klass != Data
+    }.each_with_object([]) { |klass, memo|
+      memo.concat(__registered_subscribers[klass]).uniq! if __registered_subscribers.has_key?(klass)
+    }
+  end
+
+  # @private
+  def self.__event_handlers
+    @__event_handlers ||= {}
+  end
+
+  # @private
+  def self.__build_event_handler(event_class)
+    subscriber_calls = __get_subscribers(event_class).map do |subscriber_class|
+      subscriber_class.__register_rescue_handlers
+
+      arguments = "event"
+
+      context_type, _ = subscriber_class.instance_method(:call).parameters.find do |param_type, param_name|
+        param_name == :context || param_type == :keyrest
+      end
+
+      if context_type
+        if context_type == :keyreq
+          arguments += ", context: context || {}"
+        else
+          arguments += ", context:"
+        end
+      end
+
+      if subscriber_class.__is_deferred
+        "#{subscriber_class}.enqueue(#{arguments})"
+      else
+        "#{subscriber_class}.new.__call(#{arguments})"
+      end
+    end
+
+    if subscriber_calls.empty?
+      ->(_, _) {}
+    else
+      __event_handlers[event_class] = eval <<-RUBY
+        ->(event, context) { #{subscriber_calls.join("; ")} }
+      RUBY
+    end
+  end
+
+  # @private
+  def self.__reset_subscribers
+    __registered_subscribers.clear
+    __event_handlers.clear
+
+    Rage::Events.__eager_load_subscribers
+  end
+
+  # @private
+  def self.__eager_load_subscribers
+    subscribers = Dir["#{Rage.root}/app/**/*.rb"].select do |path|
+      File.foreach(path).any? do |line|
+        line.include?("include Rage::Events::Subscriber") || line.include?("subscribe_to")
+      end
+    end
+
+    subscribers.each do |path|
+      Rage.code_loader.load_file(path)
+    end
+
+  rescue => e
+    puts "ERROR: Failed to load an event subscriber: #{e.class} (#{e.message})."
+    puts e.backtrace.join("\n")
+  end
+end
+
+require_relative "subscriber"
+
+if Rage.env.development?
+  if Rage.config.internal.initialized?
+    Rage::Events.__eager_load_subscribers
+  else
+    Rage.config.after_initialize { Rage::Events.__eager_load_subscribers }
+  end
+end

data/lib/rage/events/subscriber.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+##
+# Include this module in a class to make it an event subscriber.
+#
+# Example:
+#
+# ```ruby
+# # Define an event class
+# MyEvent = Data.define
+#
+# # Define the subscriber class
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to MyEvent
+#
+#   def call(event)
+#     puts "Received event: #{event.inspect}"
+#   end
+# end
+#
+# # Publish an event
+# Rage::Events.publish(MyEvent.new)
+# ```
+#
+# When an event matching the specified class is published, the `call` method will be invoked with the event instance.
+#
+# You can also subscribe to multiple event classes:
+#
+# ```ruby
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to EventA, EventB
+#
+#   def call(event)
+#     puts "Received event: #{event.inspect}"
+#   end
+# end
+# ```
+#
+# Subscribers are executed synchronously by default. You can make a subscriber asynchronous by passing the `deferred` option:
+#
+# ```ruby
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to MyEvent, deferred: true
+#
+#   def call(event)
+#     puts "Received event in background: #{event.inspect}"
+#   end
+# end
+# ```
+#
+# Such subscriber will be executed in the background using Rage's deferred task system.
+#
+# You can also define custom error handling for exceptions raised during event processing using `rescue_from`:
+#
+# ```ruby
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to MyEvent
+#
+#   rescue_from StandardError do |exception|
+#     puts "An error occurred: #{exception.message}"
+#   end
+# end
+# ```
+#
+# @see ClassMethods
+#
+module Rage::Events::Subscriber
+  def self.included(handler_class)
+    handler_class.extend ClassMethods
+  end
+
+  # @private
+  def call(_)
+  end
+
+  # @private
+  def __call(event, context: nil)
+    Rage.logger.with_context(self.class.__log_context) do
+      context.nil? ? call(event) : call(event, context: context.freeze)
+    rescue Exception => _e
+      e = self.class.__rescue_handlers ? __run_rescue_handlers(_e) : _e
+
+      if e
+        Rage.logger.error("Subscriber failed with exception: #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+        raise Rage::Deferred::TaskFailed if self.class.__is_deferred
+      end
+    end
+  end
+
+  module ClassMethods
+    # @private
+    attr_accessor :__event_classes, :__is_deferred, :__log_context, :__rescue_handlers
+
+    # Subscribe the class to one or more events.
+    #
+    # @param event_classes [Class, Array<Class>] one or more event classes to subscribe to
+    # @param deferred [Boolean] whether to process events asynchronously
+    def subscribe_to(*event_classes, deferred: false)
+      @__event_classes = (@__event_classes || []) | event_classes
+      @__is_deferred = !!deferred
+      @__log_context = { subscriber: name }.freeze
+
+      @__event_classes.each do |event_class|
+        Rage::Events.__register_subscriber(event_class, self)
+      end
+
+      if @__is_deferred
+        include Rage::Deferred::Task
+        alias_method :perform, :__call
+      end
+    end
+
+    # Define exception handlers for the subscriber.
+    #
+    # @param klasses [Class, Array<Class>] one or more exception classes to handle
+    # @param with [Symbol, String] the method name to call when an exception is raised
+    # @yield [exception] optional block to handle the exception
+    # @note If you do not re-raise exceptions in deferred subscribers, the subscriber will be marked as successful and Rage will not attempt to retry it.
+    def rescue_from(*klasses, with: nil, &block)
+      unless with
+        if block_given?
+          with = Rage::Internal.define_dynamic_method(self, block)
+        else
+          raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
+        end
+      end
+
+      if @__rescue_handlers.nil?
+        @__rescue_handlers = []
+      elsif @__rescue_handlers.frozen?
+        @__rescue_handlers = @__rescue_handlers.dup
+      end
+
+      @__rescue_handlers.unshift([klasses, with])
+    end
+
+    # @private
+    def inherited(klass)
+      klass.__rescue_handlers = @__rescue_handlers.freeze
+      klass.subscribe_to(*@__event_classes, deferred: @__is_deferred) if @__event_classes
+    end
+
+    # @private
+    def __register_rescue_handlers
+      return if method_defined?(:__run_rescue_handlers, false) || @__rescue_handlers.nil?
+
+      matcher_calls = @__rescue_handlers.map do |klasses, handler|
+        handler_call = instance_method(handler).arity == 0 ? handler : "#{handler}(exception)"
+
+        <<~RUBY
+          when #{klasses.join(", ")}
+            #{handler_call}
+            nil
+        RUBY
+      end
+
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def __run_rescue_handlers(exception)
+          case exception
+          #{matcher_calls.join("\n")}
+          else
+            exception
+          end
+        rescue Exception => e
+          e
+        end
+      RUBY
+    end
+  end
+end

data/lib/rage/fiber.rb

@@ -118,6 +118,14 @@ class Fiber
     "block:#{object_id}:#{@__block_channel_i}"
   end
 
+  # @private
+  def __await_channel(force = false)
+    @__fiber_channel_i ||= 0
+    @__fiber_channel_i += 1 if force
+
+    "await:#{object_id}:#{@__fiber_channel_i}"
+  end
+
   # @private
   attr_accessor :__awaited_fileno
 
@@ -148,6 +156,7 @@ class Fiber
   # @note This method should only be used when multiple fibers have to be processed in parallel. There's no need to use `Fiber.await` for single IO calls.
   def self.await(fibers)
     f, fibers = Fiber.current, Array(fibers)
+    await_channel = f.__await_channel(true)
 
     # check which fibers are alive (i.e. have yielded) and which have errored out
     i, err, num_wait_for = 0, nil, 0
@@ -169,7 +178,7 @@ class Fiber
     end
 
     # wait on async fibers; resume right away if one of the fibers errors out
-    Iodine.subscribe("await:#{f.object_id}") do |_, err|
+    Iodine.subscribe(await_channel) do |_, err|
       if err == AWAIT_ERROR_MESSAGE
         f.resume
       else
@@ -179,7 +188,7 @@ class Fiber
     end
 
     Fiber.defer(-1)
-    Iodine.defer { Iodine.unsubscribe("await:#{f.object_id}") }
+    Iodine.defer { Iodine.unsubscribe(await_channel) }
 
     # if num_wait_for is not 0 means we exited prematurely because of an error
     if num_wait_for > 0

data/lib/rage/fiber_scheduler.rb

@@ -130,10 +130,10 @@ class Rage::FiberScheduler
         Thread.current[:rage_logger] = logger
         Fiber.current.__set_result(block.call)
         # send a message for `Fiber.await` to work
-        Iodine.publish("await:#{parent.object_id}", "", Iodine::PubSub::PROCESS) if parent.alive?
+        Iodine.publish(parent.__await_channel, "", Iodine::PubSub::PROCESS) if parent.alive?
       rescue Exception => e
         Fiber.current.__set_err(e)
-        Iodine.publish("await:#{parent.object_id}", Fiber::AWAIT_ERROR_MESSAGE, Iodine::PubSub::PROCESS) if parent.alive?
+        Iodine.publish(parent.__await_channel, Fiber::AWAIT_ERROR_MESSAGE, Iodine::PubSub::PROCESS) if parent.alive?
       end
     end
 

data/lib/rage/internal.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# @private
+class Rage::Internal
+  class << self
+    # Define a method based on a block.
+    # @param klass [Class] the class to define the method in
+    # @param block [Proc] the implementation of the new method
+    # @return [Symbol] the name of the newly defined method
+    def define_dynamic_method(klass, block)
+      name = dynamic_name_seed.next.join
+      klass.define_method("__rage_dynamic_#{name}", block)
+    end
+
+    # Define a method that will call a specified method if a condition is `true` or yield if `false`.
+    # @param klass [Class] the class to define the method in
+    # @param method_name [Symbol] the method to call if the condition is `true`
+    # @return [Symbol] the name of the newly defined method
+    def define_maybe_yield(klass, method_name)
+      name = dynamic_name_seed.next.join
+
+      klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def __rage_dynamic_#{name}(condition)
+          if condition
+            #{method_name} { yield }
+          else
+            yield
+          end
+        end
+      RUBY
+    end
+
+    private
+
+    def dynamic_name_seed
+      @dynamic_name_seed ||= ("a".."j").to_a.permutation
+    end
+  end
+end

data/lib/rage/setup.rb

@@ -18,3 +18,5 @@ Rage.code_loader.setup
 Rage.config.run_after_initialize!
 
 require_relative "#{Rage.root}/config/routes"
+
+Rage.config.internal.initialized!

data/lib/rage/templates/config-environments-production.rb

@@ -8,4 +8,5 @@ Rage.configure do
   # Specify the logger
   config.logger = Rage::Logger.new(STDOUT)
   config.log_level = Logger::INFO
+  config.log_formatter = Rage::JSONFormatter.new
 end

data/lib/rage/version.rb

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

data/lib/rage-rb.rb

@@ -26,6 +26,10 @@ module Rage
     Rage::Deferred
   end
 
+  def self.events
+    Rage::Events
+  end
+
   def self.routes
     Rage::Router::DSL.new(__router)
   end
@@ -135,9 +139,11 @@ module Rage
   autoload :Cable, "rage/cable/cable"
   autoload :OpenAPI, "rage/openapi/openapi"
   autoload :Deferred, "rage/deferred/deferred"
+  autoload :Events, "rage/events/events"
 end
 
 module RageController
 end
 
 require_relative "rage/env"
+require_relative "rage/internal"

data/rage.gemspec

@@ -33,4 +33,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "zeitwerk", "~> 2.6"
   spec.add_dependency "rack-test", "~> 2.1"
   spec.add_dependency "rake", ">= 12.0"
+  spec.add_dependency "logger"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.18.0
 platform: ruby
 authors:
 - Roman Samoilov
 bindir: exe
 cert_chain: []
-date: 2025-08-20 00:00:00.000000000 Z
+date: 2025-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - rsamoi@icloud.com
 executables:
@@ -102,11 +116,11 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".yardopts"
+- ARCHITECTURE.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
-- OVERVIEW.md
 - README.md
 - Rakefile
 - exe/rage
@@ -137,11 +151,14 @@ files:
 - lib/rage/deferred/task.rb
 - lib/rage/env.rb
 - lib/rage/errors.rb
+- lib/rage/events/events.rb
+- lib/rage/events/subscriber.rb
 - lib/rage/ext/active_record/connection_pool.rb
 - lib/rage/ext/setup.rb
 - lib/rage/fiber.rb
 - lib/rage/fiber_scheduler.rb
 - lib/rage/hooks.rb
+- lib/rage/internal.rb
 - lib/rage/logger/json_formatter.rb
 - lib/rage/logger/logger.rb
 - lib/rage/logger/text_formatter.rb

data/OVERVIEW.md

@@ -1,83 +0,0 @@
-### Table of Contents
-
-[API Workflow](#api-workflow)<br>
-[Executing Controller Actions](#executing-controller-actions)<br>
-[Cable Workflow](#cable-workflow)<br>
-[OpenAPI Workflow](#openapi-workflow)<br>
-[Design Principles](#design-principles)<br>
-
-### API Workflow
-
-The following diagram describes some of Rage's internal components and the way they interact with each other:
-
-![overview](https://github.com/rage-rb/rage/assets/2270393/0d45bbe3-622c-4b17-b8d8-552c567fecb3)
-
-### Executing Controller Actions
-
-When `Rage::Router::DSL` parses the `config/routes.rb` file and calls the `Rage::Router::Backend` class, it registers actions and stores handler procs.
-
-Consider we have the following controller:
-
-```ruby
-class UsersController < RageController::API
-  before_action :find_user
-  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
-
-  def show
-    render json: @user
-  end
-
-  private
-
-  def find_user
-    @user = User.find(params[:id])
-  end
-
-  def render_not_found(_)
-    render status: :not_found
-  end
-end
-```
-
-Before processing requests to `UsersController#show`, Rage has to [register](https://github.com/rage-rb/rage/blob/master/lib/rage/controller/api.rb#L11) the show action. Registering means defining a new method that will look like this:
-
-```ruby
-class UsersController
-  def __run_show
-    find_user
-    show
-  rescue ActiveRecord::RecordNotFound => e
-    render_not_found(e)
-  end
-end
-```
-
-After that, Rage will create and store a handler proc that will look exactly like this:
-
-```ruby
-->(env, params) { UsersController.new(env, params).__run_show }
-```
-
-All of this happens at boot time. Once the request comes in at runtime, Rage will only need to retrieve the handler proc defined earlier and call it.
-
-### Cable Workflow
-
-The following diagram describes the components of a `Rage::Cable` application:
-
-![cable](https://github.com/user-attachments/assets/86db2091-f93a-44f8-9512-c4701770d09e)
-
-### OpenAPI Workflow
-
-The following diagram describes the flow of `Rage::OpenAPI`:
-
-<img width="800" src="https://github.com/user-attachments/assets/b4a87b1e-9a0f-4432-a3e9-0106ff546f3f" />
-
-### Design Principles
-
-* **Lean Happy Path:** we try to execute as many operations as possible during server initialization to minimize workload during request processing. Additionally, new features should be designed to avoid impacting the framework performance for users who do not utilize those features.
-
-* **Performance Over Code Style:** we recognize the distinct requirements of framework and client code. Testability, readability, and maintainability are crucial for client code used in application development. Conversely, library code addresses different tasks and should be designed with different objectives. In library code, performance and abstraction to enable future modifications while maintaining backward compatibility take precedence over typical client code concerns, though testability and readability remain important.
-
-* **Rails Compatibility:** Rails compatibility is a key objective to ensure a seamless transition for developers. While it may not be feasible to replicate every method implemented in Rails, the framework should function in a familiar and expected manner.
-
-* **Single-Threaded Fiber-Based Approach:** each request is processed in a separate, isolated execution context (Fiber), pausing whenever it encounters blocking I/O. This single-threaded approach eliminates thread synchronization overhead, leading to enhanced performance and simplified code.