cxz / rage

Fast web framework compatible with Rails.

Rage

Inspired by Deno and built on top of Iodine, this is a Ruby web framework that is based on the following design principles:

• Rails compatible API - Rails' API is clean, straightforward, and simply makes sense. It was one of the reasons why Rails was so successful in the past.

• High performance - some think performance is not a major metric for a framework, but it's not true. Poor performance is a risk, and in today's world, companies refuse to use risky technologies.

• API-only - the only technology we should be using to create web UI is JavaScript. Using native technologies is always the most flexible, scalable, and simple solution in the long run. Check out Vite if you don't know where to start.

• Acceptance of modern Ruby - the framework includes a fiber scheduler, which means your code never blocks while waiting on IO.

Installation

Install the gem:

$ gem install rage-rb

Create a new app:

$ rage new my_app

Switch to your new application and install dependencies:

$ cd my_app
$ bundle

Start up the server and visit http://localhost:3000.

$ rage s

Start coding!

Getting Started

This gem is designed to be a drop-in replacement for Rails in API mode. Public API is mostly expected to match Rails, however, sometimes it's a little bit more strict.

Check out in-depth API docs for more information:

• Controller API
• Routing API
• Fiber API
• Logger API

Also, see the changelog and upcoming-releases for currently supported and planned features.

Example

A sample controller could look like this:

require "net/http"

class PagesController < RageController::API
  rescue_from SocketError do |_|
    render json: { message: "error" }, status: 500
  end

  before_action :set_metadata

  def show
    page = Net::HTTP.get(URI("https://httpbin.org/json"))
    render json: { page: page, metadata: @metadata }
  end

  private

  def set_metadata
    @metadata = { format: "json", time: Time.now.to_i }
  end
end

Apart from RageController::API as a parent class, this is mostly a regular Rails controller. However, the main difference is under the hood - Rage runs every request in a separate fiber. During the call to Net::HTTP.get, the fiber is automatically paused, enabling the server to process other requests. Once the HTTP request is finished, the fiber will be resumed, potentially allowing to process hundreds of requests simultaneously.

To make this controller work, we would also need to update config/routes.rb. In this case, the file would look the following way:

Rage.routes.draw do
  get "page", to: "pages#show"
end

ℹ️ Note: Rage will automatically pause a fiber and continue to process other fibers on HTTP, PostgreSQL, and MySQL calls. Calls to Thread.join and Ractor.join will also automatically pause the current fiber.

Additionally, Fiber.await can be used to run several requests in parallel:

require "net/http"

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")) },
    ])

    render json: { pages: pages }
  end
end

ℹ️ Note: When using Fiber.await, it is important to wrap any instance of IO into a fiber using Fiber.schedule.

Benchmarks

hello world

class ArticlesController < ApplicationController
  def index
    render json: { hello: "world" }
  end
end

waiting on IO

require "net/http"

class ArticlesController < ApplicationController
  def index
    Net::HTTP.get(URI("<endpoint-that-responds-in-one-second>"))
    head :ok
  end
end

Upcoming releases

Version	Changes
0.2 ✅	Gem configuration by env. Add skip_before_action. Add rescue_from. Router updates:  • make the root helper work correctly with scope;  • support the defaults option;
0.3 ✅	CLI updates:  • routes task;  • console task; Support the :if and :unless options in before_action. Allow to set response headers.
0.4 ✅	Expose the params object. Support header authentication with authenticate_with_http_token. Router updates:  • add the resources route helper;  • add the namespace route helper;
0.5 ✅	Add request logging.
0.6	Automatic code reloading in development with Zeitwerk.
0.7	Expose the send_data and send_file methods.
0.8	Support conditional get with etag and last_modified.
0.9	Expose the cookies and session objects.
1.0	Implement Iodine-based equivalent of Action Cable.

Development

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.

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.

Contributing

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.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Rage project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.