rage-rb 1.20.1 → 1.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8aa7e9daf1be975a84d7d1106d80add30bdfd77e1419b00f7482d8bf426f5e86
-  data.tar.gz: 58a2c72cc2add61f0c2d288a82806191241d8f09ce18657e09f4606c537acd49
+  metadata.gz: 7120d5b1b4f9ae8307d199389fe7efbffff3a950d3d312b80c954a00b0c0572e
+  data.tar.gz: d3ce27d3cfa545ac38e7b3a7091c24bdd394ab954860da1418a97a16c65ef482
 SHA512:
-  metadata.gz: 07db2cb1fb418630c4ce99121a88c010e84893c0d6b52a8dd7a6251b99a56fd1666b42b0269d91b8686779fd76c3ee9df72965d82484dcacf16cd3fc4cf787a9
-  data.tar.gz: a078573af7ccf125145ba63514c291436b34552862384073062868f19ae08326b06bc1bf9ade39c75d53f8ab024df8a4d1a9041a29ca5c4c3b8e51846905e137
+  metadata.gz: aeb7938480349b63ddf30525b7bf89b6c214cf12e1b859311f6c8c7976f4c20866897fbb8cbaefa271fcf65234905b97d0428a1b6f85fb307b91f415abc7538c
+  data.tar.gz: 78b9c08dc3769fcec16ec011699d06246e7177d0459e0e4a39a592e5f62386b5142da133337a53eccb2f1c9175a3986a064e0bc16395708901de2c61080acede

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [1.21.0] - 2026-02-25
+
+### Added
+
+- [Cable] Add RSpec test helpers (#210).
+- [Cable] Add support for `stream_for`/`broadcast_to` (#207).
+- Add `skills` CLI (#218).
+- Support inline context for `Rage::Logger` (#206).
+
+### Fixed
+
+- Ensure correct log context isolation for intersecting fibers (#205).
+- Ensure Cable middleware don't duplicate when mounted in routes (#202).
+- Documentation updates by [@cuneyter](https://github.com/cuneyter) (#200).
+- Rely on `Rack::Session` for mounted apps (#201).
+
+### Fixed
+
 ## [1.20.1] - 2026-02-10
 
 ### Fixed

data/README.md

@@ -6,190 +6,208 @@
 ![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)
 
-Rage is a high-performance Ruby web framework that combines the developer experience of Rails with the scalability of fiber-based concurrency. Designed for API-first applications, it allows you to handle massive traffic loads using standard synchronous Ruby code - no complex async/await syntax required.
+**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.
 
-If you love Rails but need better performance for I/O-heavy workloads, Rage provides the perfect balance: familiar conventions, low overhead, and a commitment to stability.
+Rage uses Rails compatibility as a foundation and provides backend primitives optimized for a single-runtime model: background jobs that run in-process, WebSockets without external dependencies, object-oriented domain events, and automatic API documentation.
 
-## Why Rage?
+## Why Rage
 
-Building high-performance APIs in Ruby shouldn't mean abandoning the conventions you know. Rage gives you Rails-like controllers, routing, and patterns, but runs on **fiber-based concurrency** that makes your application naturally non-blocking. When your code waits on database queries, HTTP calls, or other I/O, Rage automatically handles thousands of other requests instead of sitting idle.
+Modern backends are more than request/response cycles. They require:
 
-Rage was built to solve the performance and stability gaps that often drive teams to migrate away from Ruby, providing a modern engine that keeps the ecosystem competitive.
+* Asynchronous execution
+* Background jobs
+* Real-time communication
+* Observability and telemetry
+* Clear domain boundaries
 
-**Key capabilities:**
+In the Ruby ecosystem, these concerns typically mean more infrastructure: Redis, Sidekiq, separate worker processes, custom logging solutions, and multiple deployment units.
 
-- **Rails compatibility** - Familiar controller API, routing DSL, and conventions. Migrate gradually or start fresh.
-- **True concurrency** - Fiber-based architecture handles I/O without threads, locks, or async/await syntax. Your code looks synchronous but runs concurrently.
-- **Zero-dependency WebSockets** - Action Cable-compatible real-time features that work out-of-the-box without Redis, even in multi-process mode.
-- **Auto-generated OpenAPI** - Documentation generated from your controllers using simple comment tags.
-- **In-process Background jobs** - A durable, persistent queue that runs inside your app process. No Redis or separate worker processes required.
-- **Built-in Observability** - Track and measure application behavior with `Rage::Telemetry`. Integrate with external monitoring platforms or build custom observability solutions.
-- **Stable and focused** - Our goal is that the task "Upgrade Rage" never appears in your ticketing system. We focus strictly on APIs, maintain long-term deprecation cycles, and ensure that most updates are as simple as a `bundle update`.
+Rage takes a different approach: **collapse backend concerns into a single runtime** by embracing Ruby's fiber-based concurrency model. This reduces operational complexity while keeping familiar Ruby ergonomics.
 
-Rage is API-only by design. Modern applications benefit from clear separation between backend and frontend, and Rage focuses exclusively on doing APIs well.
+### Unified Runtime in Action
 
-## Installation
+Here's what single runtime looks like in practice:
 
-Install the gem:
+```ruby
+class OrdersController < RageController::API
+  def create
+    order = Order.create!(order_params)
 
-```
-$ gem install rage-rb
-```
+    # Schedule background job - runs in-process, no Redis needed
+    SendOrderConfirmation.enqueue(order.id)
 
-Create a new app:
+    # Publish domain event - subscribers execute immediately or async
+    Rage::Events.publish(OrderPlaced.new(order: order))
 
-```
-$ rage new my_app
-```
+    # Broadcast to WebSocket subscribers - no Action Cable/Redis needed
+    Rage::Cable.broadcast("orders", { status: "created", order_id: order.id })
 
-Switch to your new application and install dependencies:
+    render json: order, status: :created
+  end
+end
 
-```
-$ cd my_app
-$ bundle
-```
+# Background job - runs in the same process, persisted to disk
+class SendOrderConfirmation
+  include Rage::Deferred::Task
+
+  def perform(order_id)
+    order = Order.find(order_id)
+    OrderMailer.confirmation(order).deliver
+  end
+end
 
-Start up the server and visit http://localhost:3000.
+# Domain event - typed, object-oriented
+OrderPlaced = Data.define(:order)
 
-```
-$ rage s
+# Event subscriber
+class UpdateInventory
+  include Rage::Events::Subscriber
+  subscribe_to OrderPlaced
+
+  def call(event)
+    Inventory.decrement(event.order.items.length)
+  end
+end
 ```
 
-Start coding!
+This all runs in a single process. No external queues, no separate worker dynos, no Redis for pub/sub.
 
-## How It Works
+## Coming from Rails?
 
-Rage runs each request in a separate fiber. When your code performs I/O operations - HTTP requests, database queries, file reads - the fiber automatically pauses, and Rage processes other requests. When the I/O completes, the fiber resumes exactly where it left off.
+Rage keeps the parts of Rails that work - controllers, routing, Active Record compatibility, and conventions - but rethinks how backend systems are run.
 
-This happens transparently. You write normal Ruby code, and Rage handles the concurrency.
+Instead of adding separate job queues, Redis, and multiple deployment units as your app grows, Rage uses Ruby's fiber-based concurrency to run APIs, background jobs, WebSockets, and domain events **in the same process**.
 
-### Example
+You write familiar synchronous Ruby code. Rage handles the concurrency.
 
-Here's a controller that fetches data from an external API:
+**What changes:**
 
-```ruby
-require "net/http"
+- One deployment unit instead of API servers + worker processes
+- No Redis required for jobs or broadcasts
+- Domain events as objects, not string-based notifications
+- OpenAPI specs generated automatically from your code
 
-class PagesController < RageController::API
-  rescue_from SocketError do |_|
-    render json: { message: "error" }, status: 500
-  end
+**What stays the same:**
 
-  before_action :set_metadata
+- Controller conventions and routing DSL
+- Active Record integration
+- Incremental adoption for existing Rails apps
 
-  def show
-    page = Net::HTTP.get(URI("https://httpbin.org/json"))
-    render json: { page: page, metadata: @metadata }
-  end
+Think of Rage as Rails ergonomics with a runtime designed for modern API systems, where operational simplicity is a first-class concern.
 
-  private
+## Core Ideas
 
-  def set_metadata
-    @metadata = { format: "json", time: Time.now.to_i }
-  end
-end
-```
+### 1. Unified Backend Runtime
 
-This looks like a standard Rails controller, and it is - except during `Net::HTTP.get`, Rage automatically pauses this fiber and processes other requests. When the HTTP call completes, Rage resumes exactly where it left off. This happens automatically for HTTP requests, PostgreSQL, MySQL, and other I/O operations.
+Rage runs HTTP APIs, background jobs, and WebSockets in the same process by default:
 
-The routes are equally familiar:
+- No separate worker processes
+- No Redis required for jobs or broadcasts
+- One deployment unit for most applications
 
-```ruby
-Rage.routes.draw do
-  get "page", to: "pages#show"
-end
-```
+This simplifies both local development and production setup.
 
-### Parallel Execution
+For high-scale scenarios, Rage supports multi-process deployments and allows Rage processes to communicate directly when needed.
 
-Need to make multiple I/O calls? Use `Fiber.await` to run them concurrently:
+### 2. API-First, Rails-Compatible
 
-```ruby
-require "net/http"
+Rage provides a familiar Rails-like programming model with API-focused improvements:
 
-class PagesController < RageController::API
-  def index
-    pages = Fiber.await([
-      Fiber.schedule { Net::HTTP.get(URI("https://httpbin.org/json")) },
-      Fiber.schedule { Net::HTTP.get(URI("https://httpbin.org/html")) },
-    ])
+- Controllers and routing that feel like Rails
+- Active Record compatibility
+- Incremental adoption for existing Rails applications
+- OpenAPI specs auto-generated from your code
 
-    render json: { pages: pages }
-  end
-end
-```
+Rails compatibility is the foundation. Rage builds on top of that foundation with new primitives designed for high-concurrency, API-first architectures.
 
-Instead of waiting for each request sequentially, Rage executes them concurrently and waits for all to complete.
+### 3. Built-in Asynchronous Execution
 
-## Two Ways to Use Rage
+Rage ships with **fiber-based, in-process background jobs**:
 
-**Standalone**: Create new services with `rage new`. You get a clean project structure, CLI tools, and everything needed to build high-performance APIs from scratch.
+- Zero setup - no Redis, no configuration
+- Jobs persist across restarts
+- Scheduled and executed within the same runtime using fibers for concurrency
 
-**Rails Integration**: Add Rage to existing Rails applications for gradual migration. Use Rage for new endpoints or high-traffic routes while keeping the rest of your Rails app unchanged. See the [Rails Integration guide](https://rage-rb.dev/docs/rails) for details.
+For teams that need distributed job processing, Rage works with existing solutions. But most applications can start simple and stay simple.
 
-## Documentation
+### 4. Structured Domain Events
 
-- [Getting Started](https://rage-rb.dev/docs/intro/) - Core concepts and setup
-- [Controllers](https://rage-rb.dev/docs/controllers/) - Request handling and callbacks
-- [Routing](https://rage-rb.dev/docs/routing/) - RESTful routes and namespaces
-- [WebSockets](https://rage-rb.dev/docs/websockets/) - Real-time communication
-- [OpenAPI](https://rage-rb.dev/docs/openapi/) - Auto-generated documentation
-- [Background Jobs](https://rage-rb.dev/docs/deferred/) - In-process queue system
-- [API Reference](https://rage-rb.dev/api/) - Detailed API documentation
+Rage includes a built‑in event bus designed for **object‑oriented domain events**:
 
-For contributors, check the [architecture doc](https://github.com/rage-rb/rage/blob/main/ARCHITECTURE.md) to understand how Rage's components work together.
+* Events are classes with explicit attributes, not hashes or strings
+* Subscribers listen to event classes or mixins
+* Type-safe and refactorable
 
-## Performance
+This encourages clear domain modeling and avoids the brittleness of string-based notification systems.
 
-Rage's fiber-based architecture delivers high throughput with minimal overhead. By stripping away the "framework tax", Rage gives your team more leeway to write slow-but-maintainable Ruby code without compromising the end-user experience.
+### 5. Observability by Design
 
-#### Simple JSON responses
+Observability is not an afterthought:
 
-```ruby
-class BenchmarksController < ApplicationController
-  def index
-    render json: { hello: "world" }
-  end
-end
-```
+- Structured logging by default
+- Dedicated observability interface for HTTP, background, and real-time features
+- OpenAPI specifications generated automatically from the running application
 
-![Requests per second](https://github.com/user-attachments/assets/7bb783f8-5d1b-4e7d-b14d-dafe370d1acc)
+API contracts stay in sync with code by default - no separate documentation pipelines.
 
+### 6. Performance That Enables Simplicity
 
-#### I/O-bound operations
+Rage's fiber-based concurrency delivers strong performance for I/O-heavy workloads, but performance is a means to an end: operational simplicity.
 
-```ruby
-class BenchmarksController < ApplicationController
-  def index
-    Net::HTTP.get(URI("<endpoint-that-responds-in-one-second>"))
-    head :ok
-  end
-end
-```
+By handling concurrency efficiently, Rage lets you:
 
-![Time to complete 100 requests](https://github.com/user-attachments/assets/5155a65f-2f11-4303-b5e4-a74d3d123c16)
+- Run fewer servers
+- Deploy fewer services
+- Reduce infrastructure by handling workloads that traditionally required separate microservices
 
-#### Database Queries
+The goal is to let teams write maintainable Ruby code while natively handling massive concurrency, eliminating the need for premature optimization or infrastructure sprawl.
 
-```ruby
-class BenchmarksController < ApplicationController
-  def show
-    render json: World.find(rand(1..10_000))
-  end
-end
-```
+## Philosophy
+
+Rage is intentionally conservative about change.
+
+The framework prioritizes:
+
+- **Stable public APIs**
+- **Long deprecation cycles**
+- **Minimal external dependencies**
+
+The goal is to let teams build systems that **age well** - without constant rewrites or growing infrastructure complexity.
+
+Our aspiration: the task "Upgrade Rage" never appears in your ticketing system. Most updates should be as simple as `bundle update`.
+
+## What Rage Is (and Isn't)
+
+**Rage is:**
+
+- Focused on backend APIs
+- Opinionated about operational simplicity
+- Designed for long-term stability
+- Rails-compatible but architecturally independent
+
+**Rage is not:**
+
+- A full-stack framework - no view layer, no asset pipeline
+- A Rails clone - compatibility is a bridge, not the destination
+- Trying to do everything - deliberate scope boundaries
 
-![Requests per second-2](https://github.com/user-attachments/assets/06f64a08-316f-4b24-ba2d-39ac395366aa)
+## Who Rage Is For
 
-## Development
+Rage is a good fit if you:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+- Build API-only backends in Ruby
+- Care about operational simplicity over maximum flexibility
+- Want fewer moving parts in production
+- Prefer explicit, object-oriented design
+- Value long-term stability over cutting-edge features
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Learn More
 
-## Contributing
+- 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)
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/rage-rb/rage. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/rage-rb/rage/blob/main/CODE_OF_CONDUCT.md).
+Contributions and thoughtful feedback are welcome.
 
 ## License
 

data/lib/rage/all.rb

@@ -36,7 +36,3 @@ require_relative "middleware/request_id"
 require_relative "middleware/body_finalizer"
 
 require_relative "telemetry/telemetry"
-
-if defined?(Sidekiq)
-  require_relative "sidekiq_session"
-end

data/lib/rage/cable/cable.rb

@@ -53,7 +53,11 @@ module Rage::Cable
       end
     end
 
-    Rage.with_middlewares(application, Rage.config.cable.middlewares)
+    chain = Rage.with_middlewares(application, Rage.config.cable.middlewares)
+    application.define_singleton_method(:__rage_app_name) { "Rage::Cable" }
+    chain.define_singleton_method(:__rage_root_app) { application }
+
+    chain
   end
 
   # @private

data/lib/rage/cable/channel.rb

@@ -289,6 +289,32 @@ class Rage::Cable::Channel
       @__periodic_timers << [callback, every]
     end
 
+    # Broadcast data to all the clients subscribed to a channel-local stream.
+    #
+    # @param streamable [#id, String, Symbol, Numeric, Array] an object that will be used to generate the stream name
+    # @param data [Object] the data to send to the clients
+    # @raise [ArgumentError] if the streamable object does not satisfy the type requirements
+    # @example
+    #   NotificationsChannel.broadcast_to(current_user, { message: "You have a new notification!" })
+    def broadcast_to(streamable, data)
+      Rage.cable.broadcast(__stream_name_for(streamable), data)
+    end
+
+    # @private
+    def __stream_name_for(streamables)
+      stream_name = Array(streamables).map do |streamable|
+        if streamable.respond_to?(:id)
+          "#{streamable.class.name}:#{streamable.id}"
+        elsif streamable.is_a?(String) || streamable.is_a?(Symbol) || streamable.is_a?(Numeric)
+          streamable
+        else
+          raise ArgumentError, "Unable to generate stream name. Expected an object that responds to `id`, got: #{streamable.class}"
+        end
+      end
+
+      "#{name}:#{stream_name.join(":")}"
+    end
+
     protected
 
     def set_up_periodic_timers
@@ -407,13 +433,39 @@ class Rage::Cable::Channel
     !!@__subscription_rejected
   end
 
-  # Subscribe to a stream.
+  # Subscribe to a stream global stream. Global streams are not associated with any specific channel instance and can be used to broadcast data to multiple channels at once.
   #
   # @param stream [String] the name of the stream
+  # @raise [ArgumentError] if the stream name is not a String
+  # @example Subscribe to a stream
+  #   class NotificationsChannel < Rage::Cable::Channel
+  #     def subscribed
+  #       stream_from "notifications"
+  #     end
+  #   end
+  # @example Broadcast to the stream
+  #   Rage::Cable.broadcast("notifications", { message: "A new member has joined!" })
   def stream_from(stream)
+    raise ArgumentError, "Stream name must be a String" unless stream.is_a?(String)
     Rage.cable.__protocol.subscribe(@__connection, stream, @__params)
   end
 
+  # Subscribe to a local stream. Local streams are associated with a specific channel instance and can be used to send data to the current channel only.
+  #
+  # @param streamable [#id, String, Symbol, Numeric, Array] an object that will be used to generate the stream name
+  # @raise [ArgumentError] if the streamable object does not satisfy the type requirements
+  # @example Subscribe to a stream
+  #   class NotificationsChannel < Rage::Cable::Channel
+  #     def subscribed
+  #       stream_for current_user
+  #     end
+  #   end
+  # @example Broadcast to the stream
+  #   NotificationsChannel.broadcast_to(current_user, { message: "You have a new notification!" })
+  def stream_for(streamable)
+    stream_from(self.class.__stream_name_for(streamable))
+  end
+
   # Broadcast data to all the clients subscribed to a stream.
   #
   # @param stream [String] the name of the stream