rage-rb 1.17.1 → 1.19.0

data/lib/rage-rb.rb

@@ -6,67 +6,115 @@ require "iodine"
 require "pathname"
 
 module Rage
+  # Builds the Rage application with the configured middlewares.
   def self.application
     with_middlewares(Application.new(__router), config.middleware.middlewares)
   end
 
+  # Builds the Rage application which delegates Rails requests to `Rails.application`.
   def self.multi_application
     Rage::Router::Util::Cascade.new(application, Rails.application)
   end
 
+  # Shorthand to access {Rage::Cable Rage::Cable}.
+  # @return [Rage::Cable]
   def self.cable
     Rage::Cable
   end
 
+  # Shorthand to access {Rage::OpenAPI Rage::OpenAPI}.
+  # @return [Rage::OpenAPI]
   def self.openapi
     Rage::OpenAPI
   end
 
+  # Shorthand to access {Rage::Deferred Rage::Deferred}.
+  # @return [Rage::Deferred]
   def self.deferred
     Rage::Deferred
   end
 
+  # Shorthand to access {Rage::Events Rage::Events}.
+  # @return [Rage::Events]
+  def self.events
+    Rage::Events
+  end
+
+  # Configure routes for the Rage application.
+  # @return [Rage::Router::DSL::Handler]
+  # @example
+  #   Rage.routes.draw do
+  #     root to: "users#index"
+  #   end
   def self.routes
     Rage::Router::DSL.new(__router)
   end
 
+  # @private
   def self.__router
     @__router ||= Rage::Router::Backend.new
   end
 
+  # @private
+  def self.__log_processor
+    @__log_processor ||= Rage::LogProcessor.new
+  end
+
+  # Access the Rage configuration.
+  # @return [Rage::Configuration] the Rage configuration instance.
   def self.config
     @config ||= Rage::Configuration.new
   end
 
+  # Configure Rage using a block.
+  # @example
+  #   Rage.configure do |config|
+  #     config.log_level = :debug
+  #   end
   def self.configure(&)
     config.instance_eval(&)
     config.__finalize
   end
 
+  # Access the current Rage environment.
+  # @return [Rage::Env] the Rage environment instance
+  # @example
+  #   if Rage.env.development?
+  #     puts "Running in development mode"
+  #   end
   def self.env
     @__env ||= Rage::Env.new(ENV["RAGE_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development")
   end
 
+  # Access the current Gem groups based on the Rage environment.
   def self.groups
     [:default, Rage.env.to_sym]
   end
 
+  # Access the root path of the Rage application.
+  # @return [Pathname] the root path
   def self.root
     @root ||= Pathname.new(".").expand_path
   end
 
+  # Access the Rage logger.
+  # @return [Rage::Logger] the Rage logger instance
   def self.logger
     @logger ||= config.logger
   end
 
+  # Load middlewares into the Rage application.
+  # @deprecated This method is deprecated and has been merged into `Rage.application`.
   def self.load_middlewares(_)
     puts "`Rage.load_middlewares` is deprecated and has been merged into `Rage.application`. Please remove this call."
   end
 
+  # @private
   def self.code_loader
     @code_loader ||= Rage::CodeLoader.new
   end
 
+  # @private
   def self.patch_active_record_connection_pool
     patch = proc do
       is_connected = ActiveRecord::Base.connection_pool rescue false
@@ -90,6 +138,7 @@ module Rage
     end
   end
 
+  # Load Rake tasks for the Rage application.
   def self.load_tasks
     Rage::Tasks.init
   end
@@ -135,9 +184,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.1
+  version: 1.19.0
 platform: ruby
 authors:
 - Roman Samoilov
 bindir: exe
 cert_chain: []
-date: 2025-08-21 00:00:00.000000000 Z
+date: 2025-12-03 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
@@ -130,18 +144,22 @@ files:
 - lib/rage/cookies.rb
 - lib/rage/deferred/backends/disk.rb
 - lib/rage/deferred/backends/nil.rb
+- lib/rage/deferred/context.rb
 - lib/rage/deferred/deferred.rb
-- lib/rage/deferred/metadata.rb
 - lib/rage/deferred/proxy.rb
 - lib/rage/deferred/queue.rb
 - 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/log_processor.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.

data/lib/rage/deferred/metadata.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-##
-# Metadata for deferred tasks.
-# The class encapsulates the metadata associated with a deferred task, and allows to store it without modifying the task instance.
-#
-class Rage::Deferred::Metadata
-  def self.build(task, args, kwargs)
-    request_id = Thread.current[:rage_logger][:tags][0] if Thread.current[:rage_logger]
-
-    [
-      task,
-      args.empty? ? nil : args,
-      kwargs.empty? ? nil : kwargs,
-      nil,
-      request_id
-    ]
-  end
-
-  def self.get_task(metadata)
-    metadata[0]
-  end
-
-  def self.get_args(metadata)
-    metadata[1]
-  end
-
-  def self.get_kwargs(metadata)
-    metadata[2]
-  end
-
-  def self.get_attempts(metadata)
-    metadata[3]
-  end
-
-  def self.get_request_id(metadata)
-    metadata[4]
-  end
-
-  def self.inc_attempts(metadata)
-    metadata[3] = metadata[3].to_i + 1
-  end
-end