rage-rb 1.22.1 → 1.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c18be377e162e14f77e7709fc573ff35cb9965796f9451af4e05baac5da095ca
-  data.tar.gz: 9d6193d3a72322f0d9edb702f512975451cac38d32a7505b943065222aa45115
+  metadata.gz: b488d2ab6a7ebcc33ae77a768f55e9277b796c39c5a7451e32a823f4e7a8a848
+  data.tar.gz: c1e55ecf8182587ced30f1c0af834136edbd4e06d0466dfaf6685387d0ebb3d6
 SHA512:
-  metadata.gz: 1ceffe055ffce47aca8970ee09de970665532ff4551afcbd0bf5efb9e55a380762e0b135f889b92be1acd6ba77c3d77d9025616e3d99ee75a6bfb4ccec5fbd4e
-  data.tar.gz: d9052e5e4c78aaca8425b2b7ae60622d275273ff85b18304db0657007103845c720465e744e73b077a180ae00813959c30288f174b798ec26e9518aec9062da0
+  metadata.gz: 0ed0b0e62b74d3847804613ec77da801ceb2784dda9dc81895c93c6438a07377a82a5ff3ac4099bee8d4d9698ef51e2ac12233067d0672f3b5bdf97374e2fbc6
+  data.tar.gz: 6b6b8d71317c165d7ff5d3a1942cd81aeeeb5978f3672fc1de32464f4d4e3ed8f10171345a11db2e3427aff4cd84868403922541701c5464ce4260d96690250b

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 ## [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
+- [SSE] Ensure connection is closed for single-value SSE streams by [@jsxs0](https://github.com/jsxs0) (#264).
+- Ensure task ID seed is always greater than timestamps in existing WAL files by [@Abishekcs](https://github.com/Abishekcs) (#255)
+- Correctly load routes in Rails apps (#249).
+- [SSE] Ensure connection is closed when raw SSE stream raises by [@jsxs0](https://github.com/jsxs0) (#248).
+- [OpenAPI] Alba parser: silent fallback for unresolvable association resources by [@pratyush07-hub](https://github.com/pratyush07-hub) (#258).
+- Fix `Rage::UploadedFile#close` (#262).
+
+### Added
+- [SSE] Add tests for log context propagation across fiber boundaries by [@jsxs0](https://github.com/jsxs0) (#267).
+- Add singular `resource` routing with plural controller mapping and document the helper by [@anuj-pal27](https://github.com/anuj-pal27) (#247).
+- [SSE] Add support for unbounded streams (#266).
+- [OpenAPI] Support OpenAPI generation for file parameters by [@Digvijay-x1](https://github.com/Digvijay-x1) (#229).
+- [Deferred] Add configurable retry options by [@Digvijay-x1](https://github.com/Digvijay-x1) (#225).
+- [SSE] Add unit tests for `SSE::ConnectionProxy` by [@jsxs0](https://github.com/jsxs0) (#245).
+- Custom renderer support by [@anuj-pal27](https://github.com/anuj-pal27) (#244).
+- [SSE] Add graceful shutdown support for SSE streams by [@tmchow](https://github.com/tmchow) (#261).
+
 ## [1.22.1] - 2026-04-01
 
 ### 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

@@ -4,7 +4,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/rage-rb.svg)](https://badge.fury.io/rb/rage-rb)
 ![Tests](https://github.com/rage-rb/rage/actions/workflows/main.yml/badge.svg)
-![Ruby Requirement](https://img.shields.io/badge/Ruby-3.2%2B-%23f40000)
+![Ruby Requirement](https://img.shields.io/badge/Ruby-3.3%2B-%23f40000)
 
 **Rage** is an API-first Ruby framework with a modern, fiber-based runtime that enables transparent, non-blocking concurrency while preserving familiar developer ergonomics. It focuses on **capability and operational simplicity**, letting teams build production-grade systems in a single, coherent runtime.
 
@@ -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/all.rb

@@ -36,3 +36,4 @@ require_relative "middleware/request_id"
 require_relative "middleware/body_finalizer"
 
 require_relative "telemetry/telemetry"
+require_relative "sse/sse"

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