rage-rb 1.23.0 → 1.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbc12eab5d13d5570107f5c7bf6d0b68f6f652eccc1eaafefdb47ef92ed3b264
-  data.tar.gz: 7adca2c0e96d38ca69c32f4fc12b03984b6aa46578d48d084645e11891915e99
+  metadata.gz: b488d2ab6a7ebcc33ae77a768f55e9277b796c39c5a7451e32a823f4e7a8a848
+  data.tar.gz: c1e55ecf8182587ced30f1c0af834136edbd4e06d0466dfaf6685387d0ebb3d6
 SHA512:
-  metadata.gz: cb010618b1afebee5baa5fee44963d8cdf4f1543769b79ee81d26e9a0815c3ea59d6b0cf4dad2f53adabbe8d26ae0688876d2a0f690e1497173469446ba4a9e8
-  data.tar.gz: ee292c1c8b93fed32dbe015e6de898df1f0bb63ede69deb2b1eb41cddee1e339ade19ed8981682697721b02c3923bb8782358616c5d7c264cc0d465887b6e79b
+  metadata.gz: 0ed0b0e62b74d3847804613ec77da801ceb2784dda9dc81895c93c6438a07377a82a5ff3ac4099bee8d4d9698ef51e2ac12233067d0672f3b5bdf97374e2fbc6
+  data.tar.gz: 6b6b8d71317c165d7ff5d3a1942cd81aeeeb5978f3672fc1de32464f4d4e3ed8f10171345a11db2e3427aff4cd84868403922541701c5464ce4260d96690250b

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [1.24.0] - 2026-05-12
+
+### Added
+
+- [Deferred] Add tests for log context capture and backward-compatible restore by [@jsxs0](https://github.com/jsxs0) (#274).
+- [OpenAPI] Add support for per-endpoint OAuth2/OpenID scopes via `@auth_scope` tag by [@Piyush-Goenka](https://github.com/Piyush-Goenka) (#272).
+- Reuse `define_dynamic_method` and `define_maybe_yield` methods in `RageController::API` from `Rage::Internal` by [@numice](https://github.com/numice) (#273).
+- Add the `form_actions` router configuration (#278).
+- [Deferred] Add native periodic task scheduling with multi-process leader election via `File#flock` by [@Abishekcs](https://github.com/Abishekcs) (#233).
+- [OpenAPI] Support optional attributes and `Array<>` syntax by [@ayushman1210](https://github.com/ayushman1210) (#228).
+- [Errors] Add centralized error reporting interface via `Rage.errors` and `config.error_handlers` by [@Digvijay-x1](https://github.com/Digvijay-x1) (#275).
+
+### Fixed
+
+- [OpenAPI] Fix SystemStackError in Alba parser with circular associations (#268).
+- Rewind `rack.input` when parsing request body (#279).
+
+### Changed
+
+- [Deferred] Increase default retry limit to 20 and update default retry backoff to `(attempt**4) + 10 + (rand(15) * attempt)` by  [@anuj-pal27](https://github.com/anuj-pal27) (#271).
+- Update `Rage::Cable` to use the new `PubSub` module (#281).
+
 ## [1.23.0] - 2026-04-15
 
 ### Fixed

data/CONTRIBUTING.md

@@ -0,0 +1,240 @@
+# Contributing to Rage
+
+This guide is designed to help contributors understand the project's internals, design principles, and conventions. Whether you're fixing a bug, adding a feature, or participating in GSoC, this document will help you get started.
+
+## Table of Contents
+
+- [Design Principles](#design-principles)
+- [Documentation Standards](#documentation-standards)
+- [Dynamic Code Generation](#dynamic-code-generation)
+- [Iodine Integration](#iodine-integration)
+- [The Fiber Runtime](#the-fiber-runtime)
+- [A Note on AI Usage](#a-note-on-ai-usage)
+
+## Design Principles
+
+### Performance Over Readability
+
+Rage is a framework, not application code. While readability matters, performance takes priority when the two conflict. Framework code runs on every request, so micro-optimizations compound into significant gains.
+
+This doesn't mean writing deliberately obscure code. It means accepting that some patterns which would be discouraged in application code are acceptable here when they improve performance.
+
+### Lean Happy Path
+
+The happy path should execute as little code as possible. We achieve this through:
+
+1. **Boot-time computation**: Move work to server startup whenever possible. Pre-compile routes, resolve callback chains, and build method definitions during initialization rather than on each request.
+
+2. **Feature isolation**: New features should not impact performance for users who don't use them. If a feature requires runtime checks, consider whether those checks can be eliminated through code generation or configuration.
+
+### Duplication Over Premature Abstraction
+
+Duplication is cheaper than unnecessary abstraction.
+
+Abstractions should emerge from observed patterns, not anticipated ones. When you see similar code in two places, resist the urge to immediately extract a helper. Introducing new abstraction layers or deduplicating code should only happen after the duplication has naturally occurred and proven to be a burden.
+
+A wrong abstraction is worse than duplicated code because:
+- It's harder to understand (you must trace through multiple layers)
+- It's harder to modify (changes affect all call sites)
+- It's harder to remove (it becomes load-bearing)
+
+When you do introduce an abstraction, make sure it pulls its weight.
+
+## Documentation Standards
+
+### YARD Documentation
+
+All user-facing methods must be documented using [YARD](https://yardoc.org/). Documentation comments use Markdown formatting.
+
+```ruby
+# Publish an event to all registered subscribers.
+#
+# @param event [Object] the event instance to publish
+# @param context [Hash] optional context to pass to subscribers
+# @return [void]
+#
+# @example Publishing an event
+#   Rage::Events.publish(OrderCreated.new(order: order))
+#
+# @example Publishing with context
+#   Rage::Events.publish(OrderCreated.new(order: order), context: { user_id: current_user.id })
+#
+def publish(event, context: nil)
+  # ...
+end
+```
+
+### The `@private` Tag
+
+Some methods cannot be marked `private` using Ruby's `private` keyword (e.g., they need to be called from other classes within the framework), but they are not part of the public API. These methods should be marked with the `@private` YARD tag:
+
+```ruby
+# @private
+# Used internally by the router to register controller actions.
+def __register_action(action)
+  # ...
+end
+```
+
+The `@private` tag signals to contributors:
+- This method is not part of the user-facing API
+- It can be modified or removed without deprecation
+- It can be used freely within the framework codebase
+
+## Dynamic Code Generation
+
+Rage relies heavily on dynamic code generation for both performance and flexibility. Understanding this pattern is essential for contributing to the framework.
+
+### Why Dynamic Code Generation?
+
+1. **Performance**: Generated code avoids runtime conditionals. Instead of checking "does this controller have before actions?" on every request, we generate a method that either includes the before action calls or doesn't.
+
+2. **Flexibility**: Generated code can adapt to user-defined signatures, allowing optional parameters without forcing users to accept arguments they don't need.
+
+### Examples in the Codebase
+
+#### Controller Action Registration
+
+`RageController::API.__register_action` (in `lib/rage/controller/api.rb`) generates a method for each controller action at boot time:
+
+```ruby
+class_eval <<~RUBY, __FILE__, __LINE__ + 1
+  def __run_#{action}
+    #{before_actions_chunk}
+    #{action} unless @__before_callback_rendered
+    #{after_actions_chunk}
+    [@__status, @__headers, @__body]
+    #{rescue_handlers_chunk}
+  end
+RUBY
+```
+
+This generates a single method that includes only the callbacks and exception handlers relevant to that specific action. No runtime resolution required.
+
+#### Logger Rebuilding
+
+`Rage::Logger#rebuild!` (in `lib/rage/logger/logger.rb`) generates logging methods based on the configured log level:
+
+```ruby
+if level_val < @level
+  # Log level is filtered out - generate a no-op method
+  def info(msg = nil, context = nil)
+    false
+  end
+else
+  # Generate a method that actually logs
+  def info(msg = nil, context = nil)
+    # ... logging implementation
+  end
+end
+```
+
+When logging at a level is disabled, the method becomes a no-op with zero overhead.
+
+#### Telemetry Tracer
+
+`Rage::Telemetry::Tracer#setup` (in `lib/rage/telemetry/tracer.rb`) generates tracing methods that call only the handlers registered for each span. If no handlers are registered, it generates a pass-through method.
+
+### Dynamic Keyword Arguments
+
+One pattern Rage uses extensively is dynamic keyword arguments. This allows users to define methods that accept only the parameters they care about, without requiring `**` to absorb extras.
+
+For example, an event subscriber can be defined either way:
+
+```ruby
+# Subscriber that only cares about the event
+def call(event)
+end
+
+# Subscriber that also needs context
+def call(event, context:)
+end
+```
+
+Both work regardless of whether the event was published with context. The framework inspects the method signature and generates a call that passes only the expected arguments.
+
+The `Rage::Internal.build_arguments` method (in `lib/rage/internal.rb`) implements this pattern:
+
+```ruby
+def build_arguments(method, arguments)
+  expected_parameters = method.parameters
+
+  arguments.filter_map { |arg_name, arg_value|
+    if expected_parameters.any? { |param_type, param_name| param_name == arg_name || param_type == :keyrest }
+      "#{arg_name}: #{arg_value}"
+    end
+  }.join(", ")
+end
+```
+
+This inspects the target method's parameters and generates a string containing only the arguments that method expects. The generated string is then embedded into dynamically defined code.
+
+This pattern appears in:
+- Event subscribers (accepting event with optional context)
+- Telemetry handlers (accepting various span attributes)
+- External loggers (accepting severity, message, context, etc.)
+
+## Iodine Integration
+
+Rage consists of two components: the framework (this repository) and its server, [Iodine](https://github.com/rage-rb/iodine). Iodine is not an external dependency; it's part of the Rage runtime, and its methods can be used freely within the codebase.
+
+### Useful Iodine Methods
+
+**`Iodine.run_after(milliseconds) { ... }`**: Schedule a block to run after a delay.
+
+```ruby
+Iodine.run_after(5000) do
+  cleanup_expired_sessions
+end
+```
+
+**`Iodine.run_every(milliseconds) { ... }`**: Schedule a block to run at regular intervals.
+
+```ruby
+Iodine.run_every(60_000) do
+  report_metrics
+end
+```
+
+**`Iodine.publish(channel, message, engine)`**: Send a message to subscribers. This is used for inter-fiber and inter-process communication.
+
+```ruby
+# Notify within the current process
+Iodine.publish("my_channel", "message", Iodine::PubSub::PROCESS)
+
+# Notify across all processes in the cluster
+Iodine.publish("my_channel", "message", Iodine::PubSub::CLUSTER)
+```
+
+**`Iodine.on_state(state) { ... }`**: Register callbacks for server lifecycle events.
+
+```ruby
+Iodine.on_state(:on_start) do
+  # Runs when the worker process starts
+end
+```
+
+## The Fiber Runtime
+
+### Rage::FiberWrapper
+
+`Rage::FiberWrapper` (in `lib/rage/middleware/fiber_wrapper.rb`) is the glue between the framework and the server. It sits at the top of the middleware stack and:
+
+1. Wraps every request in a Fiber
+2. Implements the defer protocol for pausing/resuming async requests
+
+When a request encounters blocking I/O (database query, HTTP request, etc.), the fiber yields. `FiberWrapper` detects this (`fiber.alive?`) and returns a special `:__http_defer__` signal to Iodine, which pauses the connection.
+
+When the I/O completes, the fiber resumes and publishes a message to notify Iodine that the response is ready. This is the mechanism that enables transparent, non-blocking concurrency.
+
+## A Note on AI Usage
+
+Contributors are free to use AI tools however they see fit.
+
+One thing to keep in mind: when delegating development to AI, the friction this removes is the very friction that enables developers to understand the system, learn, and grow as professionals.
+
+There's value in the struggle of tracing through code, understanding why something was designed a certain way, and building mental models of complex systems. Use AI to assist and accelerate, but ensure you are still engaging deeply with the architecture and the "why" behind the code you are committing.
+
+---
+
+Questions? Open an issue or reach out to the maintainers.

data/README.md

@@ -206,6 +206,7 @@ Rage is a good fit if you:
 - Documentation: [https://rage-rb.dev](https://rage-rb.dev/docs/intro)
 - API Reference: [https://rage-rb.dev/api](https://rage-rb.dev/api)
 - Architecture: [ARCHITECTURE.md](https://github.com/rage-rb/rage/blob/main/ARCHITECTURE.md)
+- Contributing: [CONTRIBUTING.md](https://github.com/rage-rb/rage/blob/main/CONTRIBUTING.md)
 
 Contributions and thoughtful feedback are welcome.
 

data/lib/rage/application.rb

@@ -23,6 +23,7 @@ class Rage::Application
     response = @exception_app.call(400, e)
 
   rescue Exception => e
+    Rage::Errors.report(e)
     response = @exception_app.call(500, e)
 
   ensure

data/lib/rage/cable/cable.rb

@@ -29,6 +29,9 @@
 # ```
 #
 module Rage::Cable
+  PUBSUB_BROADCASTER_ID = "cable"
+  private_constant :PUBSUB_BROADCASTER_ID
+
   # Create a new Cable application.
   #
   # @example
@@ -36,9 +39,6 @@ module Rage::Cable
   #     run Rage.cable.application
   #   end
   def self.application
-    # explicitly initialize the adapter
-    __adapter
-
     handler = __build_handler(__protocol)
     accept_response = [0, __protocol.protocol_definition, []]
 
@@ -61,6 +61,14 @@ module Rage::Cable
     chain
   end
 
+  # @private
+  def self.__initialize
+    if (adapter = Rage.config.pubsub.adapter)
+      adapter.add_broadcaster(PUBSUB_BROADCASTER_ID, __protocol)
+      @__adapter = adapter
+    end
+  end
+
   # @private
   def self.__router
     @__router ||= Router.new
@@ -71,11 +79,6 @@ module Rage::Cable
     @__protocol ||= Rage.config.cable.protocol.tap { |protocol| protocol.init(__router) }
   end
 
-  # @private
-  def self.__adapter
-    @__adapter ||= Rage.config.cable.adapter
-  end
-
   # @private
   def self.__build_handler(protocol)
     klass = Class.new do
@@ -125,7 +128,8 @@ module Rage::Cable
       end
 
       def log_error(e)
-        Rage.logger.error("Unhandled exception has occured - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+        Rage.logger.error("Unhandled exception has occurred - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+        Rage::Errors.report(e)
       end
     end
 
@@ -142,7 +146,7 @@ module Rage::Cable
   def self.broadcast(stream, data)
     Rage::Telemetry.tracer.span_cable_stream_broadcast(stream:) do
       __protocol.broadcast(stream, data)
-      __adapter&.publish(stream, data)
+      @__adapter&.publish(PUBSUB_BROADCASTER_ID, stream, data)
     end
 
     true
@@ -174,11 +178,6 @@ module Rage::Cable
   #     end
   #   end
 
-  module Adapters
-    autoload :Base, "rage/cable/adapters/base"
-    autoload :Redis, "rage/cable/adapters/redis"
-  end
-
   module Protocols
   end
 
@@ -191,3 +190,9 @@ require_relative "protocols/raw_web_socket_json"
 require_relative "channel"
 require_relative "connection"
 require_relative "router"
+
+if Rage.config.internal.initialized?
+  Rage::Cable.__initialize
+else
+  Rage.config.after_initialize { Rage::Cable.__initialize }
+end

data/lib/rage/cable/channel.rb

@@ -331,7 +331,8 @@ class Rage::Cable::Channel
               Fiber.schedule do
                 slice.each { |channel| callback.call(channel) }
               rescue => e
-                Rage.logger.error("Unhandled exception has occured - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+                Rage.logger.error("Unhandled exception has occurred - #{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+                Rage::Errors.report(e)
               end
             end
           end

data/lib/rage/configuration.rb

@@ -219,6 +219,14 @@ class Rage::Configuration
   end
   # @!endgroup
 
+  # @!group Error Reporter Configuration
+  # Allows configuring error reporters.
+  # @return [Rage::Configuration::ErrorReporters]
+  def error_reporters
+    @error_reporters ||= ErrorReporters.new
+  end
+  # @!endgroup
+
   # @!group OpenAPI Configuration
   # Allows configuring OpenAPI settings.
   # @return [Rage::Configuration::OpenAPI]
@@ -265,6 +273,14 @@ class Rage::Configuration
   end
   # @!endgroup
 
+  # @!group Router Configuration
+  # Allows configuring router settings.
+  # @return [Rage::Configuration::Router]
+  def router
+    @router ||= Router.new
+  end
+  # @!endgroup
+
   # @private
   def pubsub
     @pubsub ||= PubSub.new
@@ -378,6 +394,60 @@ class Rage::Configuration
     end
   end
 
+  class ErrorReporters
+    # @private
+    def initialize
+      @objects = []
+    end
+
+    # @private
+    def objects
+      @objects.dup
+    end
+
+    # Add a new error reporter.
+    # Error reporters should respond to `#call` and accept one of:
+    # - `call(exception)`
+    # - `call(exception, context: {})`
+    #
+    # @param reporter [#call]
+    # @return [self]
+    # @example
+    #   Rage.configure do
+    #     config.error_reporters << SentryReporter.new
+    #   end
+    def <<(reporter)
+      validate_input!(reporter)
+      return self if @objects.include?(reporter)
+
+      @objects << reporter
+      Rage::Errors.__send__(:__register_reporter, reporter)
+
+      self
+    end
+
+    alias_method :push, :<<
+
+    # Remove an error reporter.
+    # @param reporter [#call] the reporter to remove
+    # @example
+    #   reporter = SentryReporter.new
+    #   Rage.configure do
+    #     config.error_reporters.delete(reporter)
+    #   end
+    def delete(reporter)
+      deleted = @objects.delete(reporter)
+      Rage::Errors.__send__(:__unregister_reporter, reporter) if deleted
+      deleted
+    end
+
+    private
+
+    def validate_input!(reporter)
+      raise ArgumentError, "error reporter must respond to #call" unless reporter.respond_to?(:call)
+    end
+  end
+
   class Server
     # @!attribute port
     #   Specify the port the server will listen on.
@@ -632,33 +702,6 @@ class Rage::Configuration
         end
       end
     end
-
-    # @private
-    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
-
-    # @private
-    def adapter_config
-      config.except(:adapter)
-    end
-
-    # @private
-    def adapter
-      case config[:adapter]
-      when "redis"
-        Rage::Cable::Adapters::Redis.new(adapter_config)
-      end
-    end
   end
 
   class PublicFileServer
@@ -707,6 +750,46 @@ class Rage::Configuration
     # @private
     def initialize
       @configured = false
+      @schedule_blocks = []
+    end
+
+    # Schedule a periodic task to run at a fixed interval.
+    # @example
+    #   Rage.configure do
+    #     config.deferred.schedule do
+    #       every 5.minutes, task: ClearCache
+    #     end
+    #   end
+    def schedule(&block)
+      @schedule_blocks << block
+    end
+
+    # @private
+    # Evaluates all stored schedule blocks and returns the collected tasks.
+    # Called at boot time after all app constants are loaded.
+    def scheduled_tasks
+      @schedule_blocks.flat_map do |block|
+        dsl = ScheduleDSL.new
+        dsl.instance_eval(&block)
+        dsl.tasks
+      end
+    end
+
+    # @private
+    class ScheduleDSL
+      attr_reader :tasks
+
+      def initialize
+        @tasks = []
+      end
+
+      # Registers a task to run on a fixed interval (in seconds)
+      def every(interval, task:)
+        unless task.is_a?(Class) && task.include?(Rage::Deferred::Task)
+          raise ArgumentError, "#{task} must be a class that includes Rage::Deferred::Task"
+        end
+        @tasks << { interval:, task: }
+      end
     end
 
     # Returns the backend instance used by `Rage::Deferred`.
@@ -988,6 +1071,17 @@ class Rage::Configuration
     attr_accessor :key
   end
 
+  class Router
+    # @!attribute form_actions
+    #   Enable the automatic generation of `new` and `edit` routes via resource helpers.
+    #   @return [Boolean]
+    #   @example Enable form actions
+    #     Rage.configure do
+    #       config.router.form_actions = true
+    #     end
+    attr_accessor :form_actions
+  end
+
   # @private
   class PubSub
     attr_reader :adapter
@@ -1004,6 +1098,7 @@ class Rage::Configuration
     def config
       @config ||= begin
         config_file = Rage.root.join("config/pubsub.yml")
+        config_file = Rage.root.join("config/cable.yml") unless config_file.exist?
 
         config = if config_file.exist?
           yaml = ERB.new(config_file.read).result

data/lib/rage/controller/api.rb

@@ -185,32 +185,6 @@ class RageController::API
       klass.__wrap_parameters_options = __wrap_parameters_options
     end
 
-    # @private
-    @@__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 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
-
     # @private
     def __register_renderer(name, block)
       prepend(RageController::Renderers) unless ancestors.include?(RageController::Renderers)
@@ -240,7 +214,7 @@ class RageController::API
     def rescue_from(*klasses, with: nil, &block)
       unless with
         if block_given?
-          with = define_dynamic_method(block)
+          with = Rage::Internal.define_dynamic_method(self, block)
         else
           raise ArgumentError, "No handler provided. Pass the `with` keyword argument or provide a block."
         end
@@ -314,7 +288,7 @@ class RageController::API
     #   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]))
+      action.merge!(around: true, wrapper: Rage::Internal.define_maybe_yield(self, action[:name]))
 
       if @__before_actions && @__before_actions.frozen?
         @__before_actions = @__before_actions.dup
@@ -429,7 +403,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_dynamic_method(block)
+        action_name = Rage::Internal.define_dynamic_method(self, block)
       elsif action_name.nil?
         raise ArgumentError, "No handler provided. Pass the `action_name` parameter or provide a block."
       end
@@ -444,8 +418,8 @@ class RageController::API
         unless: _unless
       }
 
-      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[:if] = Rage::Internal.define_dynamic_method(self, action[:if]) if action[:if].is_a?(Proc)
+      action[:unless] = Rage::Internal.define_dynamic_method(self, action[:unless]) if action[:unless].is_a?(Proc)
 
       action
     end

data/lib/rage/deferred/deferred.rb

@@ -82,10 +82,16 @@ module Rage::Deferred
     )
   end
 
+  # @private
+  def self.__start_scheduler
+    Rage::Deferred::Scheduler.start(Rage.config.deferred.scheduled_tasks)
+  end
+
   # @private
   def self.__initialize
     __middleware_chain
     __load_tasks
+    __start_scheduler
   end
 
   module Backends
@@ -96,6 +102,7 @@ module Rage::Deferred
 end
 
 require_relative "task"
+require_relative "scheduler"
 require_relative "queue"
 require_relative "proxy"
 require_relative "context"