rage-rb 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88726c2fad086904077b7822723c8f840fee5beac920f21d08862c637c2c4b42
-  data.tar.gz: 37520e426a1036244dab498bbc3bb7c4155c2886ad3ecc3293f376d4dbcd6390
+  metadata.gz: 3aacbd2e65fda6a0e7a7f7a24e67f718e55fd66bd3e0a6c6d3a1a319294be44b
+  data.tar.gz: 40d3d2225cf40bf0f125884afd99a86b47b34f6dddce5fdeea0a9b5239fdfd0a
 SHA512:
-  metadata.gz: 1d635e49fc41cc68889ff1605ee1055e5ef443987b310730d91c675ca96083115f8de871a7f6d738535ee98790d2bd8b540aa476f18676fcbf6592dc719e60db
-  data.tar.gz: cdd975b3be0832d841455d736bdf1caa23d916e357ad8d20b641303b00d34dd2711fc8de34cb9a5488020ec59ec283aafc1aacb990119c075565b7c35dbfcfdd
+  metadata.gz: 288d8f707d78901e9c209cc3af075bcf3c37c7ef0ff4c24355702bd3898ab2e041afc5ab028e4cbe09e26a95f7297e01af03430ac6f126fd5d6cfa0b772f0e5e
+  data.tar.gz: 5c70306e1901176e5da774dcb153e21c382359825a2527a7de97ce75772dfdf6a510ac3ffba05486b684b55634a4173596d9469306571acf58ffff274a6185c9

data/.yardopts

@@ -0,0 +1 @@
+--exclude lib/rage/templates --markup markdown --no-private

data/Gemfile

@@ -8,3 +8,6 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
+
+gem "pg"
+gem "mysql2"

data/README.md

@@ -1,3 +1,5 @@
+<p align="center"><img height="200" src="https://github.com/rage-rb/rage/assets/2270393/d0f0834f-50e4-4b1b-a564-1f241c4ec149" /></p>
+
 # Rage
 
 [![Gem Version](https://badge.fury.io/rb/rage-rb.svg)](https://badge.fury.io/rb/rage-rb)
@@ -5,16 +7,14 @@
 
 Inspired by [Deno](https://deno.com) and built on top of [Iodine](https://github.com/rage-rb/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. I believe it was one of the reasons why Rails was so successful in the past.
+* **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 I don't believe it's true. Poor performance is a risk, and in today's world, companies refuse to use risky technologies.
+* **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. I recommend checking out [Vite](https://vitejs.dev) if you don't know where to start.
+* **API-only** - the only technology we should be using to create web UI is JavaScript. Check out [Vite](https://vitejs.dev) 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.
 
-This framework results from reflecting on [Ruby's declining popularity](https://survey.stackoverflow.co/2023/#most-popular-technologies-language) and attempting to answer why this is happening and what we, as a community, could be doing differently.
-
 ## Installation
 
 Install the gem:
@@ -40,6 +40,76 @@ $ 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](https://rage-rb.github.io/rage/RageController/API.html)
+- [Routing API](https://rage-rb.github.io/rage/Rage/Router/DSL/Handler.html)
+- [Fiber API](https://rage-rb.github.io/rage/Fiber.html)
+
+Also, see the [changelog](https://github.com/rage-rb/rage/blob/master/CHANGELOG.md) and [upcoming-releases](https://github.com/rage-rb/rage#upcoming-releases) for currently supported and planned features.
+
+### Example
+
+A sample controller could look like this:
+
+```ruby
+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:
+
+```ruby
+Rage.routes.draw do
+  get "page", to: "pages#show"
+end
+```
+
+:information_source: **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:
+
+```ruby
+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
+```
+
+:information_source: **Note**: When using `Fiber.await`, it is important to wrap any instance of IO into a fiber using `Fiber.schedule`.
+
 ## Benchmarks
 
 #### hello world
@@ -51,7 +121,7 @@ class ArticlesController < ApplicationController
   end
 end
 ```
-![Requests per second](https://github.com/rage-rb/rage/assets/2270393/7d9f408c-7cec-4cc0-a509-66c9dedc1d0a)
+![Requests per second](https://github.com/rage-rb/rage/assets/2270393/6c221903-e265-4c94-80e1-041f266c8f47)
 
 #### waiting on IO
 

data/lib/rage/application.rb

@@ -2,7 +2,9 @@
 
 class Rage::Application
   def initialize(router)
-    Fiber.set_scheduler(Rage::FiberScheduler.new)
+    Iodine.on_state(:on_start)  do
+      Fiber.set_scheduler(Rage::FiberScheduler.new)
+    end
     @router = router
   end
 

data/lib/rage/cli.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "thor"
-require "iodine"
-require "rack"
+require "rage"
 
 module Rage
   class CLI < Thor
@@ -20,8 +19,10 @@ module Rage
       app = ::Rack::Builder.parse_file("config.ru")
       app = app[0] if app.is_a?(Array)
 
-      ::Iodine.listen service: :http, handler: app
-      ::Iodine.threads = 1
+      ::Iodine.listen service: :http, handler: app, port: Rage.config.port
+      ::Iodine.threads = Rage.config.threads_count
+      ::Iodine.workers = Rage.config.workers_count
+
       ::Iodine.start
     end
   end

data/lib/rage/configuration.rb

@@ -0,0 +1,10 @@
+class Rage::Configuration
+  attr_accessor :port, :workers_count
+  attr_reader :threads_count
+
+  def initialize
+    @threads_count = 1
+    @workers_count = -1
+    @port = 3000
+  end
+end

data/lib/rage/controller/api.rb

@@ -2,6 +2,11 @@
 
 class RageController::API
   class << self
+    # @private
+    # used by the router to register a new action;
+    # registering means defining a new method which calls the action, makes additional calls (e.g. before actions) and
+    # sends a correct response down to the server;
+    # returns the name of the newly defined method;
     def __register_action(action)
       raise "The action '#{action}' could not be found for #{self}" unless method_defined?(action)
 
@@ -23,37 +28,143 @@ class RageController::API
         ""
       end
 
+      rescue_handlers_chunk = if @__rescue_handlers
+        lines = @__rescue_handlers.map do |klasses, handler|
+          <<-RUBY
+          rescue #{klasses.join(", ")} => __e
+            #{handler}(__e)
+            [@__status, @__headers, @__body]
+          RUBY
+        end
+
+        lines.join("\n")
+      else
+        ""
+      end
+
       class_eval <<-RUBY
         def __run_#{action}
           #{before_actions_chunk}
           #{action}
 
           [@__status, @__headers, @__body]
+
+          #{rescue_handlers_chunk}
         end
       RUBY
     end
 
-    # Register a new `before_action` hook.
+    # @private
+    attr_writer :__before_actions, :__rescue_handlers
+
+    # @private
+    # pass the variable down to the child; the child will continue to use it until changes need to be made;
+    # only then the object will be copied; the frozen state communicates that the object is shared with the parent;
+    def inherited(klass)
+      klass.__before_actions = @__before_actions.freeze
+      klass.__rescue_handlers = @__rescue_handlers.freeze
+    end
+
+    ############
+    #
+    # PUBLIC API
+    #
+    ############
+
+    # Register a global exception handler. Handlers are inherited and matched from bottom to top.
+    #
+    # @param klasses [Class, Array<Class>] exception classes to watch on
+    # @param with [Symbol] the name of a handler method. The method must take one argument, which is the raised exception. Alternatively, you can pass a block, which must also take one argument.
+    # @example
+    #   rescue_from User::NotAuthorized, with: :deny_access
+    #
+    #   def deny_access(exception)
+    #     head :forbidden
+    #   end
+    # @example
+    #   rescue_from User::NotAuthorized do |_|
+    #     head :forbidden
+    #   end
+    # @note Unlike Rails, the handler must always take an argument. Use `_` if you don't care about the actual exception.
+    def rescue_from(*klasses, with: nil, &block)
+      unless with
+        if block_given?
+          name = ("a".."z").to_a.sample(15).join
+          with = define_method("__#{name}", &block)
+        else
+          raise "No handler provided. Pass the `with` keyword argument or provide a block."
+        end
+      end
+
+      if @__rescue_handlers.nil?
+        @__rescue_handlers = []
+      elsif @__rescue_handlers.frozen?
+        @__rescue_handlers = @__rescue_handlers.dup
+      end
+
+      @__rescue_handlers.unshift([klasses, with])
+    end
+
+    # Register a new `before_action` hook. Calls with the same `action_name` will overwrite the previous ones.
     #
     # @param action_name [String] the name of the callback to add
     # @param only [Symbol, Array<Symbol>] restrict the callback to run only for specific actions
     # @param except [Symbol, Array<Symbol>] restrict the callback to run for all actions except specified
     # @example
     #   before_action :find_photo, only: :show
+    #
     #   def find_photo
-    #     ...
+    #     Photo.first
     #   end
     def before_action(action_name, only: nil, except: nil)
-      (@__before_actions ||= []) << {
-        name: action_name,
-        only: only && Array(only),
-        except: except && Array(except)
-      }
+      if @__before_actions && @__before_actions.frozen?
+        @__before_actions = @__before_actions.dup
+      end
+
+      action = { name: action_name, only: only && Array(only), except: except && Array(except) }
+      if @__before_actions.nil?
+        @__before_actions = [action]
+      elsif i = @__before_actions.find_index { |a| a[:name] == action_name }
+        @__before_actions[i] = action
+      else
+        @__before_actions << action
+      end
+    end
+
+    # Prevent a `before_action` hook from running.
+    #
+    # @param action_name [String] the name of the callback to skip
+    # @param only [Symbol, Array<Symbol>] restrict the callback to be skipped only for specific actions
+    # @param except [Symbol, Array<Symbol>] restrict the callback to be skipped for all actions except specified
+    # @example
+    #   skip_before_action :find_photo, only: :create
+    def skip_before_action(action_name, only: nil, except: nil)
+      i = @__before_actions&.find_index { |a| a[:name] == action_name }
+      raise "The following action was specified to be skipped but cannot be found: #{self}##{action_name}" unless i
+
+      @__before_actions = @__before_actions.dup if @__before_actions.frozen?
+
+      if only.nil? && except.nil?
+        @__before_actions.delete_at(i)
+        return
+      end
+
+      action = @__before_actions[i].dup
+      if only
+        action[:except] ? action[:except] |= Array(only) : action[:except] = Array(only)
+      end
+      if except
+        action[:only] = Array(except)
+      end
+
+      @__before_actions[i] = action
     end
   end # class << self
 
+  # @private
   DEFAULT_HEADERS = { "content-type" => "application/json; charset=utf-8" }.freeze
 
+  # @private
   def initialize(env, params)
     @__env = env
     @__params = params
@@ -72,7 +183,7 @@ class RageController::API
   #   render status: :ok
   # @example
   #   render plain: "hello world", status: 201
-  # @note `render` doesn't terminate execution of the action, so if you want to exit an action after rendering, you need to do something like 'render(...) and return'
+  # @note `render` doesn't terminate execution of the action, so if you want to exit an action after rendering, you need to do something like `render(...) and return`.
   def render(json: nil, plain: nil, status: nil)
     raise "Render was called multiple times in this action" if @__rendered
     @__rendered = true
@@ -81,7 +192,7 @@ class RageController::API
       @__body << if json
         json.is_a?(String) ? json : json.to_json
       else
-        set_header("content-type", "text/plain; charset=utf-8")
+        __set_header("content-type", "text/plain; charset=utf-8")
         plain
       end
 
@@ -116,7 +227,8 @@ class RageController::API
 
   private
 
-  def set_header(key, value)
+  # copy-on-write implementation for the headers object
+  def __set_header(key, value)
     @__headers = @__headers.dup if DEFAULT_HEADERS.equal?(@__headers)
     @__headers[key] = value
   end

data/lib/rage/fiber.rb

@@ -1,9 +1,38 @@
 class Fiber
+  # @private
   def __set_result(result)
     @__result = result
   end
 
+  # @private
   def __get_result
     @__result
   end
+
+  # Wait on several fibers at the same time. Calling this method will automatically pause the current fiber, allowing the
+  #   server to process other requests. Once all fibers have completed, the current fiber will be automatically resumed.
+  #
+  # @param fibers [Fiber, Array<Fiber>] one or several fibers to wait on. The fibers must be created using the `Fiber.schedule` call.
+  # @example
+  #   Fiber.await(
+  #     Fiber.schedule { request_1 },
+  #     Fiber.schedule { request_2 },
+  #   )
+  # @note This method should only be used when multiple fibers have to be processed in parallel. There's no need to use `Fiber.await` for single IO calls.
+  def self.await(*fibers)
+    f = Fiber.current
+
+    num_wait_for = fibers.count(&:alive?)
+    return fibers.map(&:__get_result) if num_wait_for == 0
+
+    Iodine.subscribe("await:#{f.object_id}") do
+      num_wait_for -= 1
+      f.resume if num_wait_for == 0
+    end
+
+    Fiber.yield
+    Iodine.defer { Iodine.unsubscribe("await:#{f.object_id}") }
+
+    fibers.map(&:__get_result)
+  end
 end

data/lib/rage/fiber_scheduler.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
+require "resolv"
+
 class Rage::FiberScheduler
+  def initialize
+    @root_fiber = Fiber.current
+  end
+
   def io_wait(io, events, timeout = nil)
     f = Fiber.current
     ::Iodine::Scheduler.attach(io.fileno, events, timeout&.ceil || 0) { f.resume }
@@ -84,8 +90,14 @@ class Rage::FiberScheduler
   end
 
   def fiber(&block)
+    f = Fiber.current
+    inner_schedule = f != @root_fiber
+
     fiber = Fiber.new(blocking: false) do
       Fiber.current.__set_result(block.call)
+    ensure
+      # send a message for `Fiber.await` to work
+      Iodine.publish("await:#{f.object_id}", "") if inner_schedule
     end
     fiber.resume
 

data/lib/rage/router/backend.rb

@@ -21,8 +21,8 @@ class Rage::Router::Backend
       path_full = path.sub(OPTIONAL_PARAM_REGEXP, "/#{$1}")
       path_optional = path.sub(OPTIONAL_PARAM_REGEXP, "")
 
-      on(method, path_full, handler)
-      on(method, path_optional, handler)
+      on(method, path_full, handler, constraints: constraints)
+      on(method, path_optional, handler, constraints: constraints)
       return
     end
 
@@ -166,6 +166,7 @@ class Rage::Router::Backend
 
   def find(env, derived_constraints)
     method, path = env["REQUEST_METHOD"], env["PATH_INFO"]
+    path.delete_suffix!("/") if path.end_with?("/") && path.length > 1
 
     current_node = @trees[method]
     return nil unless current_node

data/lib/rage/router/dsl.rb

@@ -10,6 +10,7 @@ class Rage::Router::DSL
   end
 
   class Handler
+    # @private
     def initialize(router)
       @router = router
 
@@ -122,6 +123,10 @@ class Rage::Router::DSL
         path = path.delete_suffix("/") if path.end_with?("/")
       end
 
+      if path == "/" && @path_prefixes.any?
+        path = ""
+      end
+
       path_prefix = @path_prefixes.any? ? "/#{@path_prefixes.join("/")}" : nil
       module_prefix = @module_prefixes.any? ? "#{@module_prefixes.join("/")}/" : nil
 

data/lib/rage/setup.rb

@@ -2,5 +2,6 @@ Iodine.patch_rack
 
 project_root = Pathname.new(".").expand_path
 
+require_relative "#{project_root}/config/environments/#{Rage.env}"
 Dir["#{project_root}/app/**/*.rb"].each { |path| require_relative path }
 require_relative "#{project_root}/config/routes"

data/lib/rage/templates/config-application.rb

@@ -1,4 +1,6 @@
 require "bundler/setup"
-Bundler.require(:default)
+
+require "rage"
+Bundler.require(*Rage.groups)
 
 require "rage/setup"

data/lib/rage/templates/config-environments-development.rb

@@ -0,0 +1,7 @@
+Rage.configure do |config|
+  # Specify the number of server processes to run. Defaults to number of CPU cores.
+  config.workers_count = 1
+
+  # Specify the port the server will listen on.
+  config.port = 3000
+end

data/lib/rage/templates/config-environments-production.rb

@@ -0,0 +1,7 @@
+Rage.configure do |config|
+  # Specify the number of server processes to run. Defaults to number of CPU cores.
+  # config.workers_count = ENV.fetch("WEB_CONCURRENCY", 1)
+
+  # Specify the port the server will listen on.
+  config.port = 3000
+end

data/lib/rage/templates/config-environments-test.rb

@@ -0,0 +1,7 @@
+Rage.configure do |config|
+  # Specify the number of server processes to run. Defaults to number of CPU cores.
+  config.workers_count = 1
+
+  # Specify the port the server will listen on.
+  config.port = 3000
+end

data/lib/rage/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rage
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/rage-rb.rb

@@ -17,6 +17,22 @@ module Rage
     @__router ||= Rage::Router::Backend.new
   end
 
+  def self.config
+    @config ||= Rage::Configuration.new
+  end
+
+  def self.configure
+    yield(config)
+  end
+
+  def self.env
+    @__env ||= ENV["RAGE_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+  end
+
+  def self.groups
+    [:default, Rage.env.to_sym]
+  end
+
   module Router
     module Strategies
     end
@@ -29,6 +45,7 @@ end
 require_relative "rage/application"
 require_relative "rage/fiber"
 require_relative "rage/fiber_scheduler"
+require_relative "rage/configuration"
 
 require_relative "rage/router/strategies/host"
 require_relative "rage/router/backend"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Roman Samoilov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-21 00:00:00.000000000 Z
+date: 2023-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -61,6 +61,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -72,6 +73,7 @@ files:
 - lib/rage.rb
 - lib/rage/application.rb
 - lib/rage/cli.rb
+- lib/rage/configuration.rb
 - lib/rage/controller/api.rb
 - lib/rage/fiber.rb
 - lib/rage/fiber_scheduler.rb
@@ -86,6 +88,9 @@ files:
 - lib/rage/templates/Gemfile
 - lib/rage/templates/app-controllers-application_controller.rb
 - lib/rage/templates/config-application.rb
+- lib/rage/templates/config-environments-development.rb
+- lib/rage/templates/config-environments-production.rb
+- lib/rage/templates/config-environments-test.rb
 - lib/rage/templates/config-routes.rb
 - lib/rage/templates/config.ru
 - lib/rage/templates/lib-.keep