rage-rb 1.17.1 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa6f9f4b7b4e1f422fd778585be775834fbe1e8e30c523e2cac096bab71d0046
-  data.tar.gz: 776090fd9779c994c95bf4ec368cb4562c544b8fc2d99043fa0c2cb5c91903af
+  metadata.gz: 847e3debe188b3b34ffdd6b7306edeca0a053b82c0e5106b3faa37a6e43f20bf
+  data.tar.gz: 202db65e0a17d27ae94178d93ddfca940a95237450095b06c0fa4e080a6fd09a
 SHA512:
-  metadata.gz: c5bbbfc62d7da523ae2f7e1d9b3be2acaa67072fd34fe464f23ab909324c46c707983e828c451969c46cb019f11c6ca0abc026d641b44c4df5340add13c830dd
-  data.tar.gz: 814cebf4625dc114d07de548981e0a593b78f2d55dd514ca9824d68296cfabd99f79e838b2580fdc07480ed906c8081585a38d6361f33bd64c3a06a070155bed
+  metadata.gz: 74610482cca2fd1394e3ffd4bd2cf577ed78a980140e39bf359ece4050bed7497dc1845a472a3c403a6fb0cbd48c1124a1714b8e7c8352b0ed720287177418c9
+  data.tar.gz: cd7cec704b0019012d1a08aea63b97dd83e0a6ee17155228d9517575e7882482c58b4b227d6663b053cc77a2edc551e34da53d0bf9bc0463e254ca917f9e8af4

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,28 @@
 ## [Unreleased]
 
+## [1.19.0] - 2025-12-03
+
+### Added
+
+- Add ability to specify external loggers (#178).
+- Pass all of log data to deferred tasks (#173).
+- Add the `Request#route_uri_pattern` method (#175).
+- Support global log tags and context (#171, #177).
+
+### Fixed
+
+- Fix reloading in dev with user-level fibers (#170).
+
+## [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

data/lib/rage/all.rb

@@ -12,6 +12,7 @@ require_relative "uploaded_file"
 require_relative "errors"
 require_relative "params_parser"
 require_relative "code_loader"
+require_relative "log_processor"
 
 require_relative "router/strategies/host"
 require_relative "router/backend"

data/lib/rage/application.rb

@@ -4,10 +4,11 @@ class Rage::Application
   def initialize(router)
     @router = router
     @exception_app = build_exception_app
+    @log_processor = Rage.__log_processor
   end
 
   def call(env)
-    init_logger(env)
+    @log_processor.init_request_logger(env)
 
     handler = @router.lookup(env)
 
@@ -25,34 +26,11 @@ class Rage::Application
     response = @exception_app.call(500, e)
 
   ensure
-    finalize_logger(env, response, params)
+    @log_processor.finalize_request_logger(env, response, params)
   end
 
   private
 
-  DEFAULT_LOG_CONTEXT = {}.freeze
-  private_constant :DEFAULT_LOG_CONTEXT
-
-  def init_logger(env)
-    Thread.current[:rage_logger] = {
-      tags: [(env["rage.request_id"] ||= Iodine::Rack::Utils.gen_request_tag)],
-      context: DEFAULT_LOG_CONTEXT,
-      request_start: Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    }
-  end
-
-  def finalize_logger(env, response, params)
-    logger = Thread.current[:rage_logger]
-
-    duration = (
-      (Process.clock_gettime(Process::CLOCK_MONOTONIC) - logger[:request_start]) * 1000
-    ).round(2)
-
-    logger[:final] = { env:, params:, response:, duration: }
-    Rage.logger.info("")
-    logger[:final] = nil
-  end
-
   def build_exception_app
     if Rage.env.development?
       ->(status, e) do

data/lib/rage/cable/cable.rb

@@ -52,11 +52,10 @@ module Rage::Cable
         end
 
         @protocol = protocol
-        @default_log_context = {}.freeze
+        @log_processor = Rage.__log_processor
       end
 
       def on_open(connection)
-        connection.env["rage.request_id"] ||= Iodine::Rack::Utils.gen_request_tag
         schedule_fiber(connection) { @protocol.on_open(connection) }
       end
 
@@ -83,7 +82,7 @@ module Rage::Cable
 
       def schedule_fiber(connection)
         Fiber.schedule do
-          Thread.current[:rage_logger] = { tags: [connection.env["rage.request_id"]], context: @default_log_context }
+          @log_processor.init_request_logger(connection.env)
           yield
         rescue => e
           log_error(e)

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