Rage Ruby Web Framework

Rage can be used in two primary ways depending on your project needs:

1. Standalone: Use rage new to create a fresh project. This provides a clean structure, CLI tools, and everything needed to build production-ready APIs from scratch.
2. Rails Integration: Add Rage to an existing Rails application. This allows for a gradual migration where you can use Rage for new endpoints or high-traffic routes while keeping the rest of your Rails application unchanged.

Rage supports wildcard segments using the * syntax. However, there are two strict rules for using them:

1. A wildcard segment can only be in the last section of the path.
2. Wildcard segments cannot be named (unlike standard parameters like :id).

get "*", to: ->(env) { [404, {}, [{ message: "Not Found" }.to_json]] }

Rage::Cable is the component used for real-time, bidirectional messaging over WebSockets. The workflow follows a standard pattern:

1. Authenticate connections: Verify the identity of the client connecting via WebSocket.
2. Subscribe to channels: Allow authenticated connections to subscribe to specific channels to receive and send messages.

Rage uses a fiber-based architecture to handle I/O operations (such as HTTP requests, database queries, or file reads) without requiring threads, locks, or async/await syntax.

When your code performs an I/O operation, the current fiber automatically pauses, allowing Rage to process other requests in the same process. Once the I/O operation completes, the fiber resumes execution exactly where it left off. This allows you to write standard, synchronous-looking Ruby code that runs concurrently.

To start a new project with Rage, install the gem, use the rage new CLI command to scaffold your application, and then install the dependencies. You can also optionally install agent skills.

Installation Steps

1. Install the gem:

   gem install rage-rb

2. Create a new app:

   rage new my_app

3. Install dependencies:

   cd my_app
   bundle install

4. Optional: Install agent skills:

   rage skills install

5. Start the server:

   rage s

   The server will be available at http://localhost:3000.

Rage::Cable provides built-in WebSocket support for Rage apps, similar to Action Cable in Rails. It allows you to:

• Mount a separate WebSocket application.
• Define channels and connections.
• Subscribe clients to named streams.
• Broadcast messages in real time.

It uses a protocol-based system (configured via Rage.config.cable.protocol) to handle message encoding and decoding, and integrates with the project's Pub/Sub adapter for broadcasting across processes.

The Rage::Events module provides a lightweight event-driven system. To use it, you follow three steps:

1. Define an event as a data structure (e.g., using Ruby's Data.define).
2. Define a subscriber by including Rage::Events::Subscriber and using the subscribe_to macro to register it for a specific event class.
3. Publish the event using Rage::Events.publish.

Subscribers implement a call method to process the event. They can optionally accept a context argument for additional metadata.

# 1. Define an event
UserRegistered = Data.define(:user_id)

# 2. Define a subscriber
class SendWelcomeEmail
  include Rage::Events::Subscriber
  subscribe_to UserRegistered

  def call(event, context: nil)
    puts "Sending welcome email to user #{event.user_id}"
  end
end

# 3. Publish an event
Rage::Events.publish(UserRegistered.new(user_id: 1))